Makefile

PYTHON ?= python3
PIP ?= pip
VERSION ?= $(shell python -c 'import tomllib;print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])' 2>/dev/null || echo "1.0.0")

.PHONY: help install lint format typecheck test coverage audit run compose-up compose-down qdrant-init ingest version sbom scan e2e smoke docker-build docker-push clean release

help:
	@echo "════════════════════════════════════════════════════════════════"
	@echo "  Cortex Knowledge Assistant - Development & Production Commands"
	@echo "════════════════════════════════════════════════════════════════"
	@echo ""
	@echo "Development:"
	@echo "  install     - Install dependencies in development mode"
	@echo "  lint        - Run linters (flake8, pylint)"
	@echo "  format      - Format code (black, isort)"
	@echo "  typecheck   - Run mypy type checker"
	@echo "  test        - Run tests"
	@echo "  coverage    - Run tests with coverage report"
	@echo "  audit       - Security audit of dependencies"
	@echo ""
	@echo "Running:"
	@echo "  run         - Start development API server"
	@echo "  compose-up  - Start all services with Docker Compose"
	@echo "  compose-down- Stop all Docker services"
	@echo ""
	@echo "Docker:"
	@echo "  docker-build - Build production Docker images"
	@echo "  docker-push  - Push images to registry"
	@echo "  scan         - Scan Docker image for vulnerabilities"
	@echo ""
	@echo "Release:"
	@echo "  version     - Generate build_info.py with Git metadata"
	@echo "  sbom        - Generate Software Bill of Materials"
	@echo "  release     - Create a new release (requires VERSION=x.y.z)"
	@echo "  clean       - Remove build artifacts and caches"
	@echo ""
	@echo "Current version: $(VERSION)"
	@echo "════════════════════════════════════════════════════════════════"

install:
	$(PIP) install --upgrade pip
	$(PIP) install -e .[dev]

lint:
	flake8 src tests
	pylint src

format:
	black src tests
	isort src tests

typecheck:
	mypy src

test:
	pytest -q --maxfail=1

coverage:
	pytest --cov=src --cov-report=term-missing --cov-report=xml --cov-fail-under=80

audit:
	pip-audit -r requirements.txt || true

run:
	# Load environment variables from .env (if present) before starting the API
	if [ -f .env ]; then set -a; . .env; set +a; fi; \
	uvicorn cortex_ka.api.main:app --host 0.0.0.0 --port 8088 --reload

compose-up:
	docker compose -f docker/compose.yml up -d --build

compose-down:
	docker compose -f docker/compose.yml down

qdrant-init:
	$(PYTHON) -m cortex_ka.scripts.init_qdrant

ingest:
	$(PYTHON) -m cortex_ka.scripts.ingest_docs

# Developer smoke test against a running API at SMOKE_BASE_URL (default http://localhost:8088)
smoke:
	$(PYTHON) -m scripts.try_it

smoke-api:
	@echo "Checking API health at http://localhost:8088/health" && curl -fS http://localhost:8088/health | sed -n '1,200p'

smoke-ui:
	@echo "Checking UI availability at http://localhost:5173" && curl -fS http://localhost:5173 | sed -n '1,40p'

# Embed Git metadata and UTC build time into src/cortex_ka/build_info.py
version:
	@GIT_SHA=$$(git rev-parse --short=12 HEAD 2>/dev/null || echo unknown); \
	BUILD_TIME=$$(date -u +"%Y-%m-%dT%H:%M:%SZ"); \
	APP_VERSION=$$(python -c 'import tomllib,sys;print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])' 2>/dev/null || echo 0.1.0); \
	echo "Updating build_info.py with $$GIT_SHA @ $$BUILD_TIME (version $$APP_VERSION)"; \
	printf '"""Build metadata placeholders.\n\nThis file is generated by `make version`.\n"""\n\nAPP_VERSION = "%s"\nGIT_SHA = "%s"\nBUILD_TIME_UTC = "%s"\n' "$$APP_VERSION" "$$GIT_SHA" "$$BUILD_TIME" > src/cortex_ka/build_info.py

# Generate SBOM with Syft (CycloneDX JSON)
sbom:
	@command -v syft >/dev/null 2>&1 || { echo "Syft not installed. See https://github.com/anchore/syft#installation"; exit 1; }
	syft packages . -o cyclonedx-json=sbom.json
	@echo "SBOM written to sbom.json"

# Scan built image with Trivy (fails on HIGH/CRITICAL)
scan:
	@command -v trivy >/dev/null 2>&1 || { echo "Trivy not installed. See https://aquasecurity.github.io/trivy/"; exit 1; }
	docker build -f docker/Dockerfile.api -t cortex-ka:local .
	trivy image --severity HIGH,CRITICAL --exit-code 1 --ignore-unfixed cortex-ka:local

# Run end-to-end tests (marked with @pytest.mark.e2e)
e2e:
	pytest -q -m e2e


# Convenience targets to bring up/down the full Cortex development platform
cortex-up:
	bash scripts/run_cortex.sh

cortex-down:
	docker compose -f docker/compose.yml down
	- pkill -f 'uvicorn cortex_ka.api.main' || true
	- pkill -f 'vite' || true
	- pkill -f 'npm' || true

# ═══════════════════════════════════════════════════════════════════
# Docker Production Commands
# ═══════════════════════════════════════════════════════════════════

docker-build:
	@echo "Building Cortex API image v$(VERSION)..."
	docker build -f docker/Dockerfile.api -t cortex-api:$(VERSION) -t cortex-api:latest .
	@echo "Building Cortex UI image v$(VERSION)..."
	docker build -f ui/Dockerfile -t cortex-ui:$(VERSION) -t cortex-ui:latest ./ui
	@echo "✓ Images built successfully"

docker-push:
	@echo "Pushing images to registry..."
	docker push cortex-api:$(VERSION)
	docker push cortex-api:latest
	docker push cortex-ui:$(VERSION)
	docker push cortex-ui:latest
	@echo "✓ Images pushed successfully"

# ═══════════════════════════════════════════════════════════════════
# Release Management
# ═══════════════════════════════════════════════════════════════════

release:
	@echo "Creating release v$(VERSION)..."
	@if git diff-index --quiet HEAD --; then \
		git tag -a v$(VERSION) -m "Release v$(VERSION)"; \
		git push origin v$(VERSION); \
		echo "✓ Release v$(VERSION) created and pushed"; \
	else \
		echo "✗ Error: Working directory has uncommitted changes"; \
		exit 1; \
	fi

clean:
	@echo "Cleaning build artifacts..."
	rm -rf .pytest_cache/
	rm -rf .mypy_cache/
	rm -rf __pycache__/
	rm -rf src/*.egg-info/
	rm -rf dist/
	rm -rf build/
	rm -rf coverage.xml
	rm -rf htmlcov/
	rm -rf .coverage
	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
	find . -type f -name "*.pyc" -delete 2>/dev/null || true
	@echo "✓ Clean complete"

# ═══════════════════════════════════════════════════════════════════
# Quick Start (for new users)
# ═══════════════════════════════════════════════════════════════════

quickstart:
	@echo "═══════════════════════════════════════════════════════════════"
	@echo "  Cortex Quick Start"
	@echo "═══════════════════════════════════════════════════════════════"
	@echo ""
	@echo "1. Copy environment template:"
	@echo "   cp .env.example .env"
	@echo ""
	@echo "2. Edit .env and add your HuggingFace API token"
	@echo ""
	@echo "3. Start Cortex:"
	@echo "   ./cortex start"
	@echo ""
	@echo "4. Open http://localhost:3000 in your browser"
	@echo ""
	@echo "═══════════════════════════════════════════════════════════════"