Add a stateful Proxmox API console and broad handler coverage beyond the

initial QEMU slice, backed by imported contracts for majors 6–9. - Implement durable handlers for access/auth, cluster, LXC, storage, HA, firewall, Ceph, SDN, ACME, notifications, pools, mapping, and node ops - Serve an interactive Web UI with catalog browsing, demo seed controls, and OpenAPI/help surfaces - Bundle PVE 6.4-15, 7.4-16, and 8.4.5 contract revisions alongside 9.2.3 - Support in-memory runtime contract Apply (POST /ui/api/contract/apply) so /version and /api2 routes follow the selected major until restart - Expand seed profiles (including demo-cluster), migrations 007–008, TLS gateway config, Compose/Makefile tooling, and compatibility evidence - Tighten .gitignore for macOS, hidden directories (.*/), and local secrets
2026-07-16 01:08:01 +03:00
parent 003ee5d634
commit 777926487b
189 changed files with 241501 additions and 944 deletions
@@ -1,84 +1,183 @@
-PYTHON ?= python3.13
-VENV ?= .venv
-BIN := $(VENV)/bin
 COMPOSE ?= docker compose
+SERVICE_DEV := dev
+SERVICE_SIM := simulator
+PYTEST_OFFLINE := -m "not integration and not compatibility"

-.PHONY: help install format lint typecheck test test-unit test-integration test-contract coverage run dev docker-build docker-up docker-down docker-logs db-up db-down db-migrate db-reset api-import api-diff seed clean ci
+# Docker Hub release image (runtime target only — not the local bind-mount "dev" image).
+DOCKERHUB_USER ?= inecs
+IMAGE_NAME ?= proxmox-api-simulator
+VERSION ?= $(shell sed -n 's/^version = "\(.*\)"/\1/p' pyproject.toml)
+DOCKER_IMAGE ?= $(DOCKERHUB_USER)/$(IMAGE_NAME)
+PUSH_LATEST ?= 1
+
+COMPOSE_RELEASE ?= $(COMPOSE) -f docker-compose.release.yml
+HELM_CHART ?= ./helm/proxmox-api-simulator
+
+.PHONY: help install format lint typecheck test test-unit test-integration test-contract test-compatibility test-surface evidence coverage run dev up down restart logs docker-build docker-up docker-down docker-logs docker-restart db-up db-down db-migrate db-reset api-import api-diff seed clean ci ci-all shell release release-build release-up release-down release-seed helm-deps helm-template

 help: ## Show available commands
-	@awk 'BEGIN {FS = ":.*## "}; /^[a-zA-Z0-9_-]+:.*## / {printf "%-18s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+	@awk 'BEGIN {FS = ":.*## "}; /^[a-zA-Z0-9_-]+:.*## / {printf "%-22s %s\n", $$1, $$2}' $(MAKEFILE_LIST)

-install: ## Create the Python 3.13 environment and install development dependencies
-	$(PYTHON) -m venv $(VENV)
-	$(BIN)/python -m pip install --upgrade "pip>=25.1,<26"
-	$(BIN)/python -m pip install -e '.[dev]'
+install: ## Build runtime and development images
+	@test -f .env || cp .env.example .env
+	$(COMPOSE) build simulator $(SERVICE_DEV)

 format: ## Format Python sources
-	$(BIN)/ruff format .
+	$(COMPOSE) run --rm --no-deps $(SERVICE_DEV) ruff format .

 lint: ## Run Ruff lint checks
-	$(BIN)/ruff check .
+	$(COMPOSE) run --rm --no-deps $(SERVICE_DEV) ruff check .

 typecheck: ## Run strict mypy checks
-	$(BIN)/mypy
+	$(COMPOSE) run --rm --no-deps $(SERVICE_DEV) mypy

-test: ## Run all offline tests
-	$(BIN)/pytest
+test: ## Run offline unit and contract tests
+	$(COMPOSE) run --rm --no-deps $(SERVICE_DEV) pytest $(PYTEST_OFFLINE)

 test-unit: ## Run unit tests
-	$(BIN)/pytest tests/unit
+	$(COMPOSE) run --rm --no-deps $(SERVICE_DEV) pytest tests/unit

 test-integration: ## Run tests that require PostgreSQL
-	$(BIN)/pytest -m integration
+	@test -f .env || cp .env.example .env
+	$(COMPOSE) up -d postgres
+	$(COMPOSE) run --rm $(SERVICE_DEV) pytest -m integration

 test-contract: ## Run offline API contract tests
-	$(BIN)/pytest -m contract
+	$(COMPOSE) run --rm --no-deps $(SERVICE_DEV) pytest -m contract

-coverage: ## Run tests with coverage enforcement
-	$(BIN)/pytest --cov=app --cov-report=term-missing --cov-report=xml
-
-run: ## Run the application
-	$(BIN)/uvicorn app.main:app --host "$${APP_HOST:-0.0.0.0}" --port "$${APP_PORT:-8006}"
-
-dev: ## Run with auto-reload
-	$(BIN)/uvicorn app.main:app --reload --host "$${APP_HOST:-0.0.0.0}" --port "$${APP_PORT:-8006}"
-
-docker-build: ## Build the runtime image
-	$(COMPOSE) build simulator
-
-docker-up: ## Start PostgreSQL and simulator
+test-compatibility: ## Run proxmoxer smoke flow against the Compose stack
 	@test -f .env || cp .env.example .env
-	$(COMPOSE) up -d --build
+	$(COMPOSE) up -d --build --wait
+	$(COMPOSE) run --rm --entrypoint python $(SERVICE_SIM) -m app.simulation.seed_cli
+	$(COMPOSE) run --rm $(SERVICE_DEV) pytest -m compatibility

-docker-down: ## Stop local services
+test-surface: ## Probe every declared method on majors 6-9 (0x501 / 0xexception)
+	@test -f .env || cp .env.example .env
+	$(COMPOSE) up -d postgres
+	$(COMPOSE) run --rm $(SERVICE_DEV) pytest tests/compatibility/test_api_surface_probe.py -q
+
+evidence: ## Regenerate per-major verified surface evidence ledgers
+	$(COMPOSE) run --rm --no-deps $(SERVICE_DEV) python -m app.evidence_gen
+
+coverage: ## Run offline tests with coverage enforcement
+	$(COMPOSE) run --rm --no-deps $(SERVICE_DEV) pytest $(PYTEST_OFFLINE) --cov=app --cov-report=term-missing --cov-report=xml
+
+run: ## Run the application in the foreground
+	@test -f .env || cp .env.example .env
+	$(COMPOSE) up --build
+
+up: ## Start PostgreSQL, simulator, and TLS gateway
+	@test -f .env || cp .env.example .env
+	$(COMPOSE) up -d --build --wait
+
+down: ## Stop local services
 	$(COMPOSE) down

-docker-logs: ## Follow simulator logs
+restart: ## Rebuild and restart the stack
+	@test -f .env || cp .env.example .env
+	$(COMPOSE) up -d --build --force-recreate --wait
+
+logs: ## Follow logs from all services
+	$(COMPOSE) logs -f
+
+dev: ## Run the application with auto-reload in Docker
+	@test -f .env || cp .env.example .env
+	$(COMPOSE) up -d postgres migrate
+	$(COMPOSE) up simulator
+
+docker-build: ## Build runtime and development images
+	$(MAKE) install
+
+docker-up: up ## Alias for up
+
+docker-restart: ## Rebuild and recreate simulator and TLS gateway only
+	$(COMPOSE) up -d --build --force-recreate simulator tls-gateway
+
+docker-down: down ## Alias for down
+
+docker-logs: ## Follow simulator logs only
 	$(COMPOSE) logs -f simulator

 db-up: ## Start PostgreSQL only
+	@test -f .env || cp .env.example .env
 	$(COMPOSE) up -d postgres

 db-down: ## Stop PostgreSQL
 	$(COMPOSE) stop postgres

 db-migrate: ## Apply database migrations
-	$(BIN)/python -m app.db.migrate_cli
+	@test -f .env || cp .env.example .env
+	$(COMPOSE) run --rm migrate

 db-reset: ## Recreate the local database volume
 	$(COMPOSE) down -v
 	$(COMPOSE) up -d postgres
+	$(COMPOSE) run --rm migrate

 api-import: ## Import an API snapshot
-	$(BIN)/proxmox-api-contract import $(ARGS)
+	$(COMPOSE) run --rm --no-deps $(SERVICE_DEV) proxmox-api-contract import $(ARGS)

 api-diff: ## Compare API snapshots
-	$(BIN)/proxmox-api-contract diff $(ARGS)
+	$(COMPOSE) run --rm --no-deps $(SERVICE_DEV) proxmox-api-contract diff $(ARGS)

 seed: ## Seed simulation data
-	SEED_PROFILE="$${PROFILE:-small}" $(BIN)/python -m app.simulation.seed_cli
+	@test -f .env || cp .env.example .env
+	SEED_PROFILE="$${PROFILE:-small}" $(COMPOSE) run --rm --entrypoint python $(SERVICE_SIM) -m app.simulation.seed_cli
+
+shell: ## Open an interactive shell in the development container
+	$(COMPOSE) run --rm --no-deps $(SERVICE_DEV) bash

 clean: ## Remove generated local artifacts
-	rm -rf $(VENV) .coverage coverage.xml htmlcov .mypy_cache .pytest_cache .ruff_cache
+	rm -rf .coverage coverage.xml htmlcov .mypy_cache .pytest_cache .ruff_cache

-ci: format lint typecheck coverage ## Run the complete local quality gate
+ci: ## Offline quality gate + full API surface probe (Postgres)
+	$(COMPOSE) run --rm --no-deps $(SERVICE_DEV) sh -c '\
+		ruff format --check . && \
+		ruff check . && \
+		mypy && \
+		pytest $(PYTEST_OFFLINE) --cov=app --cov-report=term-missing --cov-report=xml'
+	$(MAKE) test-surface
+
+ci-all: ## Full CI: offline + surface + remaining integration + proxmoxer
+	$(MAKE) ci
+	$(MAKE) test-integration
+	$(MAKE) test-compatibility
+
+release-build: ## Build the runtime image tagged for Docker Hub (no push)
+	@test -n "$(VERSION)" || (echo "VERSION is empty; set VERSION=... or version in pyproject.toml" >&2; exit 1)
+	@echo "Building $(DOCKER_IMAGE):$(VERSION) (target=runtime)"
+	docker build \
+		--target runtime \
+		--build-arg APP_VERSION=$(VERSION) \
+		-t $(DOCKER_IMAGE):$(VERSION) \
+		$(if $(filter 1 true yes,$(PUSH_LATEST)),-t $(DOCKER_IMAGE):latest,) \
+		.
+
+release: release-build ## Build and push the runtime image to Docker Hub
+	@echo "Pushing $(DOCKER_IMAGE):$(VERSION)"
+	@docker push $(DOCKER_IMAGE):$(VERSION)
+	@if [ "$(PUSH_LATEST)" = "1" ] || [ "$(PUSH_LATEST)" = "true" ] || [ "$(PUSH_LATEST)" = "yes" ]; then \
+		echo "Pushing $(DOCKER_IMAGE):latest"; \
+		docker push $(DOCKER_IMAGE):latest; \
+	fi
+	@echo "Released $(DOCKER_IMAGE):$(VERSION)$(if $(filter 1 true yes,$(PUSH_LATEST)), and $(DOCKER_IMAGE):latest,)"
+
+release-up: ## Pull and start the published Hub stack (docker-compose.release.yml)
+	IMAGE_TAG="$${IMAGE_TAG:-$(VERSION)}" DOCKER_IMAGE="$(DOCKER_IMAGE)" $(COMPOSE_RELEASE) pull
+	IMAGE_TAG="$${IMAGE_TAG:-$(VERSION)}" DOCKER_IMAGE="$(DOCKER_IMAGE)" $(COMPOSE_RELEASE) up -d --wait
+
+release-down: ## Stop the published Hub stack
+	$(COMPOSE_RELEASE) down
+
+release-seed: ## Seed the published Hub stack (PROFILE=small by default)
+	SEED_PROFILE="$${PROFILE:-small}" IMAGE_TAG="$${IMAGE_TAG:-$(VERSION)}" DOCKER_IMAGE="$(DOCKER_IMAGE)" \
+		$(COMPOSE_RELEASE) run --rm --entrypoint python simulator -m app.simulation.seed_cli
+
+helm-deps: ## No-op placeholder (chart has no OCI dependencies)
+	@echo "Chart $(HELM_CHART) vendors PostgreSQL templates; no helm dependency update required."
+
+helm-template: ## Render Helm manifests locally (requires helm)
+	helm template pve-sim $(HELM_CHART) \
+		-f $(HELM_CHART)/values-ingress-example.yaml \
+		--set certManager.email=docs@example.com \
+		--set secret.ticketSigningKey=docs-only-signing-key