Makefile

# Makefile for OntoBricks (FastAPI)
#
# All deployment values (app names, DAB target, registry coords, SQL
# warehouse, Lakebase project/branch/database, app.yaml runtime
# fallbacks) are centralised in `scripts/deploy.config.sh`. Edit that
# file to change deployment behaviour, then `make deploy`.
#
# `scripts/deploy.sh` sources the config; the bootstrap targets below
# do the same so `make bootstrap-perms` / `make bootstrap-lakebase`
# stay aligned with the rest of the workflow.

CONFIG := scripts/deploy.config.sh

.PHONY: help install test test-cov scenario-campaign run dev prod setup format lint clean \
        deploy deploy-dry-run deploy-volume deploy-no-run \
        bootstrap-perms bootstrap-lakebase \
        bundle-validate bundle-summary deploy-check \
        render-app-yaml

# Output dir for the live scenario campaign reports (JUnit + HTML).
SCENARIO_ARTIFACTS := artifacts/scenarios
# Target app for the campaign; override to hit a deployed instance:
#   make scenario-campaign ONTOBRICKS_LIVE_BASE=https://<app-url>
ONTOBRICKS_LIVE_BASE ?= http://localhost:8000

help:
	@echo "OntoBricks (FastAPI) - Available commands:"
	@echo ""
	@echo "  Development:"
	@echo "    make install      - Install dependencies"
	@echo "    make run          - Run the application locally"
	@echo "    make dev          - Run in development mode with auto-reload"
	@echo "    make setup        - Complete setup (install + configure)"
	@echo ""
	@echo "  Testing:"
	@echo "    make test              - Run tests"
	@echo "    make test-cov          - Run tests with coverage"
	@echo "    make scenario-campaign - Run the live E2E scenario campaign (opt-in, billable)"
	@echo "                             → JUnit + HTML reports in $(SCENARIO_ARTIFACTS)/"
	@echo "                             App must be running (make dev); override target with"
	@echo "                             ONTOBRICKS_LIVE_BASE=<url>"
	@echo ""
	@echo "  Code Quality:"
	@echo "    make format       - Format code with black"
	@echo "    make lint         - Lint code with flake8"
	@echo ""
	@echo "  Deployment (Databricks Asset Bundles — dev sandbox only):"
	@echo "    Edit values in: $(CONFIG)"
	@echo "    make deploy              - Deploy + start the dev sandbox app (Lakebase backend)"
	@echo "    make deploy-dry-run      - Run ALL pre-deploy checks (preflight/validate/resources), no changes"
	@echo "    make deploy-volume       - Deploy + start the dev sandbox app (Volume-only backend)"
	@echo "    make deploy-no-run       - Deploy without starting the app (Lakebase target)"
	@echo "    make render-app-yaml     - Re-render app.yaml from template + config"
	@echo "    make bootstrap-perms     - Grant app SP CAN_MANAGE on itself + CAN_MANAGE_RUN on the analytics job"
	@echo "    make bootstrap-lakebase  - Grant the app SP USAGE/DML on the Lakebase registry schema"
	@echo "    make bundle-validate     - Validate the bundle config (target from deploy.config.sh)"
	@echo "    make bundle-summary      - Preview what will deploy (target from deploy.config.sh)"
	@echo "    make deploy-check        - Read-only deploy prerequisite check (see documentation/DEPLOY_CHECKLIST.md)"
	@echo ""
	@echo "  Maintenance:"
	@echo "    make clean        - Remove generated files"
	@echo ""

install:
	@echo "Installing dependencies..."
	uv venv
	uv sync --frozen --extra lakebase --extra pitfalls

setup:
	@echo "Running setup..."
	chmod +x scripts/setup.sh
	scripts/setup.sh

run:
	@echo "Starting OntoBricks (FastAPI)..."
	. .venv/bin/activate && python run.py

test:
	@echo "Running tests..."
	. .venv/bin/activate && pytest

test-cov:
	@echo "Running tests with coverage..."
	. .venv/bin/activate && pytest --cov=src --cov-report=html --cov-report=term

# ── Integration test campaign (live, opt-in scenario suites) ─────────────
# Runs every `scenario`-marked suite under tests/e2e/scenarios/ end-to-end,
# in filename order (test_scenario_1 → 2 → 3 → … → test_scenario_validation),
# against a RUNNING app and writes machine + human reports to
# $(SCENARIO_ARTIFACTS)/ (campaign.xml for CI, campaign.html to open).
#
# These are billable (warehouse + LLM) and mutate the registry the app reads,
# so they stay opt-in: this target sets ONTOBRICKS_SCENARIO_LIVE=1 for you.
# Point at another instance with `ONTOBRICKS_LIVE_BASE=<url>`. Preflight the
# app health before spending money.
#
# Run the target app with auto-reload OFF (`scripts/start.sh --no-reload`):
# Auto-Map and the KG build run for minutes in background threads whose state
# lives in the in-memory TaskManager, so any src/ save mid-campaign restarts
# uvicorn, kills the thread and makes the run fail with a misleading timeout.
scenario-campaign:
	@echo "Scenario campaign → $(ONTOBRICKS_LIVE_BASE)"
	@curl -sf "$(ONTOBRICKS_LIVE_BASE)/health" >/dev/null 2>&1 \
	  || curl -sf "$(ONTOBRICKS_LIVE_BASE)/healthz" >/dev/null 2>&1 \
	  || { echo "ERROR: no app reachable at $(ONTOBRICKS_LIVE_BASE) — start it (make dev) or set ONTOBRICKS_LIVE_BASE"; exit 1; }
	@# uvicorn's reloader is a supervisor that forks the real server, so a
	@# reload-enabled `run.py` has child processes while a no-reload one does
	@# not. Matching on "--reload"/"watchfiles" misses it: the children are
	@# plain `python3` and reload is enabled in-code, not on the command line.
	@for pid in $$(pgrep -f "[r]un.py" 2>/dev/null); do \
	  if pgrep -P $$pid >/dev/null 2>&1; then \
	    echo "WARNING: app (pid $$pid) is running WITH auto-reload — a src/ edit mid-campaign will kill Auto-Map and fail the run with a misleading timeout."; \
	    echo "         Restart it first: scripts/stop.sh && ONTOBRICKS_NO_RELOAD=1 .venv/bin/python run.py"; \
	  fi; \
	done
	@mkdir -p $(SCENARIO_ARTIFACTS)
	@echo "Running live scenarios (JUnit + HTML → $(SCENARIO_ARTIFACTS)/)..."
	. .venv/bin/activate && \
	  ONTOBRICKS_SCENARIO_LIVE=1 ONTOBRICKS_SCENARIO_CHAIN=1 \
	  ONTOBRICKS_LIVE_BASE="$(ONTOBRICKS_LIVE_BASE)" \
	  pytest tests/e2e/scenarios -m scenario -v -s --no-cov -p no:randomly \
	    --junitxml=$(SCENARIO_ARTIFACTS)/campaign.xml \
	    --html=$(SCENARIO_ARTIFACTS)/campaign.html --self-contained-html
	@echo "Reports: $(SCENARIO_ARTIFACTS)/campaign.html  (JUnit: $(SCENARIO_ARTIFACTS)/campaign.xml)"
	@echo "         $(SCENARIO_ARTIFACTS)/campaign_report.md  (validation summary, if it ran)"

format:
	@echo "Formatting code..."
	. .venv/bin/activate && black src/ tests/

lint:
	@echo "Linting code..."
	. .venv/bin/activate && flake8 src/ tests/ --max-line-length=100

clean:
	@echo "Cleaning up..."
	find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
	find . -type f -name "*.pyc" -delete
	find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
	rm -rf .pytest_cache htmlcov .coverage
	rm -rf $(SCENARIO_ARTIFACTS) artifacts
	rm -rf flask_session fastapi_session
	@echo "Clean complete!"

dev:
	@echo "Starting development server with auto-reload..."
	. .venv/bin/activate && python run.py

prod:
	@echo "Starting production server..."
	. .venv/bin/activate && uvicorn app.fastapi.main:app --host 0.0.0.0 --port 8000

# ── Deployment (DAB — Databricks Asset Bundles) ──────────────
# `scripts/deploy.sh` is the single orchestrator: it sources
# `$(CONFIG)`, renders app.yaml from app.yaml.template, runs
# `databricks bundle deploy` with --var= overrides composed from the
# config, then bootstraps app SP perms (and Lakebase schema GRANTs on
# *-lakebase targets). The DAB target defaults to `dev-lakebase` from
# `$(CONFIG)`; the `deploy-volume` target overrides on the CLI.

deploy:
	chmod +x scripts/deploy.sh
	unset APP_NAME MCP_APP_NAME REGISTRY_SCHEMA LAKEBASE_REGISTRY_SCHEMA LAKEBASE_REGISTRY_DATABASE APP_LAKEBASE_SCHEMA APP_LAKEBASE_DATABASE; scripts/deploy.sh

deploy-dry-run:
	chmod +x scripts/deploy.sh
	unset APP_NAME MCP_APP_NAME REGISTRY_SCHEMA LAKEBASE_REGISTRY_SCHEMA LAKEBASE_REGISTRY_DATABASE APP_LAKEBASE_SCHEMA APP_LAKEBASE_DATABASE; scripts/deploy.sh --dry-run

deploy-volume:
	chmod +x scripts/deploy.sh
	unset APP_NAME MCP_APP_NAME REGISTRY_SCHEMA LAKEBASE_REGISTRY_SCHEMA LAKEBASE_REGISTRY_DATABASE APP_LAKEBASE_SCHEMA APP_LAKEBASE_DATABASE; scripts/deploy.sh -t dev

deploy-no-run:
	chmod +x scripts/deploy.sh
	unset APP_NAME MCP_APP_NAME REGISTRY_SCHEMA LAKEBASE_REGISTRY_SCHEMA LAKEBASE_REGISTRY_DATABASE APP_LAKEBASE_SCHEMA APP_LAKEBASE_DATABASE; scripts/deploy.sh --no-run

render-app-yaml:
	@echo "Rendering app.yaml from app.yaml.template + $(CONFIG)..."
	@. ./$(CONFIG) && python3 scripts/_internal/_render-app-yaml.py

bootstrap-perms:
	@echo "Bootstrapping app self-permissions (config: $(CONFIG))..."
	chmod +x scripts/bootstrap/app-permissions.sh
	@. ./$(CONFIG) && scripts/bootstrap/app-permissions.sh

bootstrap-lakebase:
	@echo "Granting Lakebase schema USAGE/DML to sandbox apps (config: $(CONFIG))..."
	chmod +x scripts/bootstrap/lakebase-perms.sh
	@. ./$(CONFIG) && \
	  scripts/bootstrap/lakebase-perms.sh \
	    -i "$$LAKEBASE_PROJECT" \
	    -b "$$LAKEBASE_BRANCH" \
	    -d "$$LAKEBASE_DATABASE" \
	    -s "$$LAKEBASE_SCHEMA" \
	    -a "$$APP_NAME" -a "$$MCP_APP_NAME"

bundle-validate:
	@echo "Validating Databricks Asset Bundle (target from $(CONFIG))..."
	@. ./$(CONFIG) && \
	  . ./scripts/_internal/_ensure-instance-target.sh && \
	  ensure_instance_target "$$DAB_TARGET" && \
	  databricks bundle validate -t "$$DAB_TARGET" \
	    --var=app_name="$$APP_NAME" \
	    --var=mcp_app_name="$$MCP_APP_NAME" \
	    --var=warehouse_id="$$WAREHOUSE_ID" \
	    --var=registry_catalog="$$REGISTRY_CATALOG" \
	    --var=registry_schema="$$REGISTRY_SCHEMA" \
	    --var=registry_volume="$$REGISTRY_VOLUME" \
	    --var=neo4j_secret_scope="$$NEO4J_SECRET_SCOPE" \
	    --var=lakebase_project="$$LAKEBASE_PROJECT" \
	    --var=lakebase_branch="$$LAKEBASE_BRANCH" \
	    --var=lakebase_database_resource_segment="$$LAKEBASE_DATABASE_RESOURCE_SEGMENT" \
	    --var=lakebase_registry_schema="$$LAKEBASE_SCHEMA"

bundle-summary:
	@echo "Bundle summary (target from $(CONFIG))..."
	@. ./$(CONFIG) && \
	  . ./scripts/_internal/_ensure-instance-target.sh && \
	  ensure_instance_target "$$DAB_TARGET" && \
	  databricks bundle summary -t "$$DAB_TARGET" \
	    --var=app_name="$$APP_NAME" \
	    --var=mcp_app_name="$$MCP_APP_NAME" \
	    --var=warehouse_id="$$WAREHOUSE_ID" \
	    --var=registry_catalog="$$REGISTRY_CATALOG" \
	    --var=registry_schema="$$REGISTRY_SCHEMA" \
	    --var=registry_volume="$$REGISTRY_VOLUME" \
	    --var=neo4j_secret_scope="$$NEO4J_SECRET_SCOPE" \
	    --var=lakebase_project="$$LAKEBASE_PROJECT" \
	    --var=lakebase_branch="$$LAKEBASE_BRANCH" \
	    --var=lakebase_database_resource_segment="$$LAKEBASE_DATABASE_RESOURCE_SEGMENT" \
	    --var=lakebase_registry_schema="$$LAKEBASE_SCHEMA"

# Check deployment prerequisites (read-only — see documentation/DEPLOY_CHECKLIST.md)
deploy-check:
	@chmod +x scripts/deploy.sh
	@scripts/deploy.sh --dry-run