Makefile

# Bazel wrapper
BAZEL = ./tool/bazel

# Bazel supplies the pinned Docker Compose release for every local stack.
COMPOSE = $(BAZEL) run @rules_docker_compose//docker_compose --

# SubmitQueue compose files
COMPOSE_FILE = $(abspath service/submitqueue/docker-compose.yml)
GATEWAY_COMPOSE_FILE = $(abspath service/submitqueue/gateway/server/docker-compose.yml)
ORCHESTRATOR_COMPOSE_FILE = $(abspath service/submitqueue/orchestrator/server/docker-compose.yml)
WEB_COMPOSE_FILE = $(abspath service/submitqueue/docker-compose.web.yml)

# Fixed project name for local manual testing (tests use unique random names)
SUBMITQUEUE_LOCAL_PROJECT = submitqueue

# Stovepipe compose file (single Ping-only service)
STOVEPIPE_COMPOSE_FILE = $(abspath service/stovepipe/docker-compose.yml)
STOVEPIPE_DEBUG_COMPOSE_FILE = $(abspath service/stovepipe/docker-compose.debug.yml)

# Fixed project name for local manual testing (tests use unique random names)
STOVEPIPE_LOCAL_PROJECT = stovepipe

# Runway compose files
RUNWAY_COMPOSE_FILE = $(abspath service/runway/server/docker-compose.yml)

# Fixed project name for local manual testing (tests use unique random names)
RUNWAY_LOCAL_PROJECT = runway

# yamlfmt version for YAML formatting (override with: make fmt YAMLFMT_VERSION=v0.16.0)
YAMLFMT_VERSION ?= v0.16.0

# goimports version for Go formatting + import fixing
GOIMPORTS_VERSION ?= v0.33.0

# Proto packages: api/<domain>/<service> dirs whose protopb/ holds the generated
# stubs. Each is generated by Bazel into bazel-bin/tool/proto/api_<domain>_<service>/
# (the out_dir convention in tool/proto/BUILD.bazel) and copied back here. A
# package may hold multiple .proto files (e.g. an RPC contract plus messagequeue
# contracts); all generated stubs land in the same protopb/ dir.
PROTO_PACKAGES = api/base/change api/base/hook api/base/mergestrategy api/base/messagequeue api/runway/messagequeue api/runway api/submitqueue/gateway api/submitqueue/orchestrator api/stovepipe stovepipe/core/messagequeue submitqueue/core/messagequeue

# Set REPO_ROOT for docker-compose
export REPO_ROOT := $(shell pwd)

# Local-only credential for the reference web host. Override it for manual
# testing; production authentication is deliberately outside this demo.
export SUBMITQUEUE_WEB_TOKEN ?= test
export SUBMITQUEUE_WEB_CURSOR_SECRET ?= local-demo-cursor-secret

# Which provider the demo stack targets, and the only difference between a free
# local run and a live one. Selects a configuration directory rather than a code
# path, so adding a provider is mostly adding a directory — see
# service/submitqueue/demo/provider/README.md.
#
#   fake    a change is a URI; nothing lands anywhere. Needs nothing.
#   git     branches in a bare repository on disk; real fetch, cherry-pick, push.
#   github  real pull requests. Needs a repository and GITHUB_TOKEN.
PROVIDER ?= fake
export SQ_PROVIDER_CONFIG_DIR ?= $(REPO_ROOT)/service/submitqueue/demo/provider/$(PROVIDER)

# Which compose overlay each mode needs. This cannot live in the provider
# directory: the two config files say how the services are configured, not what
# has to be mounted or which credential has to be present for them to start.
PROVIDER_COMPOSE_FILE_fake = $(abspath service/submitqueue/docker-compose.fake.yml)
PROVIDER_COMPOSE_FILE_git = $(abspath service/submitqueue/docker-compose.git.yml)
PROVIDER_COMPOSE_FILE_github = $(abspath service/submitqueue/docker-compose.provider.yml)
PROVIDER_COMPOSE_FILE = $(PROVIDER_COMPOSE_FILE_$(PROVIDER))

# Where PROVIDER=git keeps the bare repository it lands into. Outside the
# repository, so a demo leaves nothing in a checkout, and bind-mounted rather
# than kept in a volume so `git log` on the host can show what landed.
#
# SQ_RUNWAY_CHECKOUT_DIR is deliberately not set: unset, Runway's working trees
# live in a named volume instead of on the host. See docker-compose.git.yml.
export SQ_GIT_SANDBOX_DIR ?= /tmp/sq-sandbox

# Defaults for `make land` / `make demo-requests` against the provider demo stack.
DEMO_REPO ?= behinddwalls/sq-demo
COUNT ?= 3
# How many folders demo-requests spreads its changes across, which decides how
# much they conflict: changes sharing a folder are batched in order, changes in
# different folders go out together. 0 picks one per run.
FOLDERS ?= 0
FILES ?= 3
CONCURRENCY ?= 5
STACKED ?= false
# BURST=true creates every change first, then enqueues them all at once instead
# of as each is created. Independent changes only; a stack always lands as one.
BURST ?= false
SINCE ?= 1h
LIMIT ?= 50
LAND ?= true
WATCH ?= true
QUEUE ?= demo-queue
STRATEGY ?= SQUASH_REBASE
# Where the client looks for the gateway. Left empty, every target below finds
# the running stack's published port for itself — Compose picks a fresh one on
# every start, and a number copied out of a previous run's output is the most
# common reason a demo command cannot connect. Set it to reach a gateway this
# Makefile did not start.
GATEWAY_ADDR ?=

# Resolves $(GATEWAY_ADDR), or the local stack's port when it is unset, into
# $$addr for the recipe that includes it. Not a $(shell ...) assignment: that
# would run at parse time, shelling out to Docker on every `make help`.
define resolve_gateway_addr
	addr="$(GATEWAY_ADDR)"; \
	port=$$(docker port $(SUBMITQUEUE_LOCAL_PROJECT)-gateway-service-1 8080 2>/dev/null | head -1 | sed 's/.*://'); \
	if [ -z "$$addr" ]; then \
		if [ -z "$$port" ]; then \
			echo "No gateway found: '$(SUBMITQUEUE_LOCAL_PROJECT)' is not running." >&2; \
			echo "Start it with 'make local-submitqueue-start', or name one with GATEWAY_ADDR=host:port." >&2; \
			exit 2; \
		fi; \
		addr="localhost:$$port"; \
	elif [ "$(origin GATEWAY_ADDR)" = "environment" ] && [ -n "$$port" ] && [ "$$addr" != "localhost:$$port" ]; then \
		echo "Note: GATEWAY_ADDR=$$addr is exported in your shell, so that is what will be used." >&2; \
		echo "      The stack running here is on localhost:$$port — 'unset GATEWAY_ADDR' to use it." >&2; \
	fi
endef

# Resolves which provider to create changes for into $$provider, preferring the
# one the running stack was started with.
#
# The two have to agree. A change minted for one provider is meaningless to a
# stack wired to another: fake changes point at no repository, so a stack
# running the git merger rejects every one of them as a commit it cannot find,
# and fifty requests fail identically for a reason that is nowhere in the error.
# The stack knows which provider it has — it is mounted at /etc/submitqueue —
# so a run that was not told otherwise asks it rather than guessing.
define resolve_provider
	provider="$(PROVIDER)"; \
	mounted=$$(docker inspect $(SUBMITQUEUE_LOCAL_PROJECT)-orchestrator-service-1 \
		--format '{{range .Mounts}}{{if eq .Destination "/etc/submitqueue"}}{{.Source}}{{end}}{{end}}' 2>/dev/null); \
	if [ -n "$$mounted" ]; then \
		running=$$(basename "$$mounted"); \
		if [ "$(origin PROVIDER)" = "file" ]; then \
			provider="$$running"; \
		elif [ "$$provider" != "$$running" ]; then \
			echo "Note: creating $$provider changes, but the running stack is '$$running'." >&2; \
			echo "      They have to match — a $$provider change is not something a '$$running' stack can land." >&2; \
		fi; \
	fi
endef

# Fails if git working tree is dirty. Usage: $(call assert_clean,fix command)
define assert_clean
	@if ! git diff --quiet; then \
		echo "The following files need updating:" >&2; \
		git diff --name-only >&2; \
		echo "" >&2; \
		echo "Please run '$(1)' locally and commit the changes." >&2; \
		exit 1; \
	fi
endef

.PHONY: build build-all-linux build-runway-linux build-submitqueue-gateway-client build-submitqueue-gateway-linux build-submitqueue-gateway-server build-submitqueue-orchestrator-linux build-stovepipe-linux build-stovepipe-linux-debug check-gazelle check-mocks check-tidy clean clean-proto demo-requests deps docs-build docs-serve e2e-test fmt gazelle integration-test integration-test-submitqueue-consumer integration-test-extensions integration-test-submitqueue-gateway integration-test-submitqueue-orchestrator license-fix lint lint-binary lint-fmt lint-license local-init-runway-queue-schema local-init-stovepipe-schemas local-runway-start local-runway-stop local-submitqueue-stop local-submitqueue-clean local-submitqueue-gateway-start local-submitqueue-gateway-stop local-init-submitqueue-schemas local-submitqueue-logs local-submitqueue-orchestrator-start local-submitqueue-orchestrator-stop local-submitqueue-ps local-submitqueue-restart local-submitqueue-start local-stop local-stovepipe-debug-start local-stovepipe-logs local-stovepipe-start local-stovepipe-stop mocks proto query-deps query-targets run-client-runway run-client-submitqueue-gateway run-client-submitqueue-orchestrator run-client-stovepipe run-queue-admin test test-no-cache test-race tidy tidy-bazel tidy-go web-build web-check web-e2e-test web-image-load web-install web-proto help


build: ## Build all services and examples
	@echo "Building all targets with Bazel..."
	@$(BAZEL) build //...
	@echo "Build complete!"

# Build Linux binaries required for the local docker-compose flows (local-*).
# Bazel-run integration/e2e tests do NOT need these: they build the service
# binaries hermetically as data dependencies.
build-all-linux: build-submitqueue-gateway-linux build-submitqueue-orchestrator-linux build-stovepipe-linux build-runway-linux ## Build all Linux binaries for Docker
	@echo "All Linux binaries ready for Docker"

build-runway-linux: ## Build Runway Linux binary for Docker
	@echo "Building Runway Linux binary for Docker..."
	@$(BAZEL) build --platforms=@rules_go//go/toolchain:linux_amd64 //service/runway/server:runway
	@mkdir -p .docker-bin
	@cp -f bazel-bin/service/runway/server/runway_/runway .docker-bin/runway 2>/dev/null || \
	 cp -f bazel-bin/service/runway/server/runway .docker-bin/runway
	@echo "Runway Linux binary ready at .docker-bin/runway"

build-submitqueue-gateway-client: ## Build the gateway client CLI for the host platform into bin/client
	@echo "Building gateway client..."
	@$(BAZEL) build //service/submitqueue/gateway/client:gateway
	@mkdir -p bin
	@cp -f bazel-bin/service/submitqueue/gateway/client/gateway_/gateway bin/client 2>/dev/null || \
	 cp -f bazel-bin/service/submitqueue/gateway/client/gateway bin/client
	@echo "Gateway client ready at bin/client"

build-submitqueue-gateway-linux: ## Build Gateway Linux binary for Docker
	@echo "Building Gateway Linux binary for Docker..."
	@$(BAZEL) build --platforms=@rules_go//go/toolchain:linux_amd64 //service/submitqueue/gateway/server:gateway
	@mkdir -p .docker-bin
	@cp -f bazel-bin/service/submitqueue/gateway/server/gateway_/gateway .docker-bin/gateway 2>/dev/null || \
	 cp -f bazel-bin/service/submitqueue/gateway/server/gateway .docker-bin/gateway
	@echo "Gateway Linux binary ready at .docker-bin/gateway"

build-submitqueue-gateway-server: ## Build the gateway server for the host platform into bin/server
	@echo "Building gateway server..."
	@$(BAZEL) build //service/submitqueue/gateway/server:gateway
	@mkdir -p bin
	@cp -f bazel-bin/service/submitqueue/gateway/server/gateway_/gateway bin/server 2>/dev/null || \
	 cp -f bazel-bin/service/submitqueue/gateway/server/gateway bin/server
	@echo "Gateway server ready at bin/server"

build-submitqueue-orchestrator-linux: ## Build Orchestrator Linux binary for Docker
	@echo "Building Orchestrator Linux binary for Docker..."
	@$(BAZEL) build --platforms=@rules_go//go/toolchain:linux_amd64 //service/submitqueue/orchestrator/server:orchestrator
	@mkdir -p .docker-bin
	@cp -f bazel-bin/service/submitqueue/orchestrator/server/orchestrator_/orchestrator .docker-bin/orchestrator 2>/dev/null || \
	 cp -f bazel-bin/service/submitqueue/orchestrator/server/orchestrator .docker-bin/orchestrator
	@echo "Orchestrator Linux binary ready at .docker-bin/orchestrator"

build-stovepipe-linux: ## Build Stovepipe Linux binary for Docker
	@echo "Building Stovepipe Linux binary for Docker..."
	@$(BAZEL) build --platforms=@rules_go//go/toolchain:linux_amd64 //service/stovepipe/server:stovepipe
	@mkdir -p .docker-bin
	@cp -f bazel-bin/service/stovepipe/server/stovepipe_/stovepipe .docker-bin/stovepipe 2>/dev/null || \
	 cp -f bazel-bin/service/stovepipe/server/stovepipe .docker-bin/stovepipe
	@echo "Stovepipe Linux binary ready at .docker-bin/stovepipe"

build-stovepipe-linux-debug: ## Build Stovepipe Linux debug binary for Docker/delve (symbols, no optimizations)
	@echo "Building Stovepipe Linux debug binary for Docker..."
	@$(BAZEL) build --compilation_mode=dbg --platforms=@rules_go//go/toolchain:linux_amd64 //service/stovepipe/server:stovepipe
	@mkdir -p .docker-bin
	@cp -f bazel-bin/service/stovepipe/server/stovepipe_/stovepipe .docker-bin/stovepipe-debug 2>/dev/null || \
	 cp -f bazel-bin/service/stovepipe/server/stovepipe .docker-bin/stovepipe-debug
	@echo "Stovepipe Linux debug binary ready at .docker-bin/stovepipe-debug"

check-gazelle: ## Check BUILD.bazel files are up to date
	@echo "Running Gazelle to check BUILD files..."
	@$(BAZEL) run //:gazelle
	$(call assert_clean,make gazelle)
	@echo "BUILD files are up to date."

check-mocks: mocks ## Check mock files are up to date
	$(call assert_clean,make mocks)
	@echo "Mock files are up to date."

check-tidy: tidy ## Check that go.mod and MODULE.bazel are tidy
	$(call assert_clean,make tidy)
	@echo "Module files are up to date."

clean: ## Remove the Bazel cache and bin/ (generated proto: make clean-proto)
	@echo "Cleaning with Bazel..."
	@$(BAZEL) clean
	@rm -rf bin/
	@echo "Clean complete!"

clean-proto: ## Clean generated proto files
	@echo "Cleaning generated proto files..."
	@rm -f $(foreach p,$(PROTO_PACKAGES),$(p)/protopb/*.pb.go $(p)/protopb/*.pb.yarpc.go)
	@echo "Proto clean complete!"

demo-requests: ## Create N changes, enqueue each as it is created, and watch (PROVIDER=fake|git|github COUNT=3 FOLDERS=0 FILES=3 CONCURRENCY=5 BURST=false)
	@set -e; $(resolve_gateway_addr); $(resolve_provider); \
	$(BAZEL) run //service/submitqueue/demo/requests -- \
		-provider $$provider \
		-repo $(DEMO_REPO) \
		-sandbox-dir $(SQ_GIT_SANDBOX_DIR) \
		-count $(COUNT) \
		-folders $(FOLDERS) \
		-files $(FILES) \
		-concurrency $(CONCURRENCY) \
		-stacked=$(STACKED) \
		-burst=$(BURST) \
		-addr $$addr \
		-queue $(QUEUE) \
		-strategy $(STRATEGY) \
		-land=$(LAND) -watch=$(WATCH)

deps: tidy-go ## Download and tidy Go dependencies
	@echo "Dependencies installed!"

docs-build: ## Build the documentation site into tool/docsite/build (fails on broken links)
	@$(BAZEL) run //tool/docsite:mkdocs -- build --strict --config-file $(CURDIR)/tool/docsite/mkdocs.yml --site-dir $(CURDIR)/tool/docsite/build

docs-serve: ## Serve the documentation site with live reload on a free localhost port (DOCS_PORT=8000 to pin one)
	@$(BAZEL) run //tool/docsite:mkdocs -- serve --config-file $(CURDIR)/tool/docsite/mkdocs.yml $(if $(DOCS_PORT),--dev-addr 127.0.0.1:$(DOCS_PORT))

e2e-git-test: ## Run the hermetic git E2E (real merger against a bare repo; no credentials)
	@echo "Running hermetic git end-to-end tests..."
	@$(BAZEL) test //test/e2e/submitqueue:go_default_test --test_output=errors \
		--test_filter='TestGitMergeE2E'

e2e-test: ## Run end-to-end tests (hermetic; Bazel builds all inputs; runs in parallel)
	@echo "Running end-to-end tests (parallel)..."
	@$(BAZEL) test //test/e2e/... --test_output=errors

fmt: ## Format Go and YAML code
	@echo "Formatting Go code..."
	@find . -name '*.go' -not -path './pkg/*' -not -path './bazel-*' | xargs $(BAZEL) run @rules_go//go -- run golang.org/x/tools/cmd/goimports@$(GOIMPORTS_VERSION) -w
	@echo "Formatting YAML files..."
	@$(BAZEL) run @rules_go//go -- run github.com/google/yamlfmt/cmd/yamlfmt@$(YAMLFMT_VERSION)
	@echo "Formatting complete!"

gazelle: ## Update BUILD.bazel files
	@echo "Running Gazelle to update BUILD files..."
	@$(BAZEL) run //:gazelle

integration-test: ## Run all integration tests (hermetic; Bazel builds all inputs; runs in parallel)
	@echo "Running all integration tests (parallel)..."
	@$(BAZEL) test //test/integration/... --test_output=errors

integration-test-submitqueue-consumer: ## Run Consumer integration tests
	@echo "Running Consumer integration tests..."
	@$(BAZEL) test //test/integration/submitqueue/core/consumer:go_default_test --test_output=streamed

integration-test-extensions: ## Run extension integration tests (runs in parallel)
	@echo "Running extension integration tests (parallel)..."
	@$(BAZEL) test //test/integration/submitqueue/extension/... //test/integration/extension/... --test_output=errors

integration-test-runway-merger: ## Run Runway merger extension tests (GitHub ones need SQ_GITHUB_TOKEN and SQ_GITHUB_TEST_REPO=owner/repo, else skip)
	@echo "Running Runway merger extension tests..."
	@$(BAZEL) test //test/integration/runway/... --test_output=errors

integration-test-submitqueue-gateway: ## Run Gateway integration tests
	@echo "Running Gateway integration tests..."
	@$(BAZEL) test //test/integration/submitqueue/gateway:go_default_test --test_output=streamed

integration-test-submitqueue-orchestrator: ## Run Orchestrator integration tests
	@echo "Running Orchestrator integration tests..."
	@$(BAZEL) test //test/integration/submitqueue/orchestrator:go_default_test --test_output=streamed

land: ## Land a change or a stack (PR=<url>, PRS="<url> <url>", or URI=<change-uri>)
	@if [ -z "$(PR)$(PRS)$(URI)$(URIS)" ]; then \
		echo "Usage: make land PR=https://github.com/owner/repo/pull/7"; \
		echo "   stack: make land PRS=\"<url-1> <url-2> <url-3>\"   (order is the stack order)"; \
		echo "   by uri: make land URI=github://github.com/owner/repo/pull/7/<sha>"; \
		echo "   opts: QUEUE=$(QUEUE) STRATEGY=$(STRATEGY) GATEWAY_ADDR=$(GATEWAY_ADDR)"; \
		exit 2; \
	fi
	@set -e; $(resolve_gateway_addr); \
	$(BAZEL) run //service/submitqueue/gateway/client:gateway -- \
		-addr $$addr land \
		-queue $(QUEUE) \
		-strategy $(STRATEGY) \
		$(if $(PR),-pr $(PR)) $(foreach p,$(PRS),-pr $(p)) \
		$(if $(URI),-uri $(URI)) $(foreach u,$(URIS),-uri $(u))

land-status: ## Read a landed request's status (SQID=... [QUEUE=demo-queue])
	@if [ -z "$(SQID)" ]; then echo "Usage: make land-status SQID=demo-queue/1 [QUEUE=demo-queue]"; exit 2; fi
	@set -e; $(resolve_gateway_addr); \
	$(BAZEL) run //service/submitqueue/gateway/client:gateway -- \
		-addr $$addr status -queue $(QUEUE) -sqid $(SQID)

land-list: ## Show a queue's recent requests as a table (QUEUE=demo-queue SINCE=1h LIMIT=50)
	@set -e; $(resolve_gateway_addr); \
	$(BAZEL) run //service/submitqueue/gateway/client:gateway -- \
		-addr $$addr list -queue $(QUEUE) -since $(SINCE) -limit $(LIMIT)

land-watch: ## Follow a queue's requests until they settle (QUEUE=demo-queue SINCE=15m LIMIT=50)
	@set -e; $(resolve_gateway_addr); \
	$(BAZEL) run //service/submitqueue/gateway/client:gateway -- \
		-addr $$addr watch -queue $(QUEUE) -since $(SINCE) -limit $(LIMIT)

license-fix: ## Add missing license headers to source files
	@$(BAZEL) run //tool/linter/licenseheader -- --fix

lint: lint-binary lint-fmt lint-license lint-message-id lint-queue-shard ## Run all linters
	@echo "All lint checks passed."

lint-binary: ## Check no binary file is tracked in the repository
	@$(BAZEL) run //tool/linter/binaryfile

lint-fmt: fmt ## Check code formatting (fails if unformatted)
	$(call assert_clean,make fmt)
	@echo "All code is properly formatted."

lint-license: ## Check license headers on all source files
	@$(BAZEL) run //tool/linter/licenseheader -- --check

lint-message-id: ## Check queue messages are only constructed through platform/publish
	@$(BAZEL) run //tool/linter/messageid

lint-queue-shard: ## Check every table's primary key leads with the queue column
	@$(BAZEL) run //tool/linter/queueshard

local-submitqueue-clean: ## Stop the stack and remove its volumes, images, and PROVIDER=git's sandbox
	@echo "Cleaning all services and data..."
	@# The overlay is named so that volumes it declares — Runway's checkouts —
	@# are removed too, rather than surviving as an orphan.
	@$(COMPOSE) -f $(COMPOSE_FILE) -f $(PROVIDER_COMPOSE_FILE) -f $(WEB_COMPOSE_FILE) -p $(SUBMITQUEUE_LOCAL_PROJECT) down -v --rmi local
	@rm -rf "$(SQ_GIT_SANDBOX_DIR)"
	@echo "All services, volumes, images, and $(SQ_GIT_SANDBOX_DIR) removed."

local-submitqueue-gateway-start: build-submitqueue-gateway-linux ## Start Gateway service locally (Gateway + 2 MySQL databases)
	@echo "Starting Gateway with docker-compose..."
	@$(COMPOSE) -f $(GATEWAY_COMPOSE_FILE) -p $(SUBMITQUEUE_LOCAL_PROJECT) up -d --build --wait
	@echo "Applying database schemas..."
	@$(MAKE) -s local-init-submitqueue-schemas
	@echo ""
	@echo "✅ Gateway is running!"
	@echo ""
	@$(COMPOSE) -f $(GATEWAY_COMPOSE_FILE) -p $(SUBMITQUEUE_LOCAL_PROJECT) ps
	@echo ""
	@echo "Gateway gRPC port: $$(docker port $(SUBMITQUEUE_LOCAL_PROJECT)-gateway-service-1 8080 2>/dev/null | cut -d: -f2 || echo 'unknown')"
	@echo "MySQL App port:    $$(docker port $(SUBMITQUEUE_LOCAL_PROJECT)-mysql-app-1 3306 2>/dev/null | cut -d: -f2 || echo 'unknown')"
	@echo "MySQL Queue port:  $$(docker port $(SUBMITQUEUE_LOCAL_PROJECT)-mysql-queue-1 3306 2>/dev/null | cut -d: -f2 || echo 'unknown')"

local-submitqueue-gateway-stop: ## Stop Gateway service
	@echo "Stopping Gateway services..."
	@$(COMPOSE) -f $(GATEWAY_COMPOSE_FILE) -p $(SUBMITQUEUE_LOCAL_PROJECT) down
	@echo "Gateway services stopped."

local-init-submitqueue-schemas: ## Manually apply all database schemas
	@echo "Applying storage schema to mysql-app..."
	@for file in submitqueue/orchestrator/extension/storage/mysql/schema/*.sql; do \
		echo "  - Applying $$(basename $$file)..."; \
		docker exec -i $(SUBMITQUEUE_LOCAL_PROJECT)-mysql-app-1 mysql -uroot -proot submitqueue < $$file 2>&1 | grep -v "Using a password" || true; \
	done
	@for file in submitqueue/gateway/extension/storage/mysql/schema/*.sql; do \
		echo "  - Applying $$(basename $$file)..."; \
		docker exec -i $(SUBMITQUEUE_LOCAL_PROJECT)-mysql-app-1 mysql -uroot -proot submitqueue < $$file 2>&1 | grep -v "Using a password" || true; \
	done
	@echo "Applying counter schema to mysql-app..."
	@for file in platform/extension/counter/mysql/schema/*.sql; do \
		echo "  - Applying $$(basename $$file)..."; \
		docker exec -i $(SUBMITQUEUE_LOCAL_PROJECT)-mysql-app-1 mysql -uroot -proot submitqueue < $$file 2>&1 | grep -v "Using a password" || true; \
	done
	@echo "Applying queue schema to mysql-queue..."
	@for file in platform/extension/messagequeue/mysql/schema/*.sql; do \
		echo "  - Applying $$(basename $$file)..."; \
		docker exec -i $(SUBMITQUEUE_LOCAL_PROJECT)-mysql-queue-1 mysql -uroot -proot submitqueue < $$file 2>&1 | grep -v "Using a password" || true; \
	done
	@echo "✅ All schemas applied successfully"

local-init-runway-queue-schema: ## Apply queue schema only (mysql-queue) for Runway compose stacks
	@echo "Applying queue schema to mysql-queue (Runway; consumes the merge queues)..."
	@for file in platform/extension/messagequeue/mysql/schema/*.sql; do \
		echo "  - Applying $$(basename $$file)..."; \
		docker exec -i $(RUNWAY_LOCAL_PROJECT)-mysql-queue-1 mysql -uroot -proot submitqueue < $$file 2>&1 | grep -v "Using a password" || true; \
	done
	@echo "✅ Runway queue schema applied successfully"

local-init-stovepipe-schemas: ## Apply storage (mysql-app) and queue (mysql-queue) schemas for Stovepipe compose stacks
	@echo "Applying storage schema to mysql-app..."
	@for file in platform/extension/counter/mysql/schema/*.sql; do \
		echo "  - Applying $$(basename $$file)..."; \
		docker exec -i $(STOVEPIPE_LOCAL_PROJECT)-mysql-app-1 mysql -uroot -proot submitqueue < $$file 2>&1 | grep -v "Using a password" || true; \
	done
	@for file in stovepipe/extension/storage/mysql/schema/*.sql; do \
		echo "  - Applying $$(basename $$file)..."; \
		docker exec -i $(STOVEPIPE_LOCAL_PROJECT)-mysql-app-1 mysql -uroot -proot submitqueue < $$file 2>&1 | grep -v "Using a password" || true; \
	done
	@echo "Applying queue schema to mysql-queue..."
	@for file in platform/extension/messagequeue/mysql/schema/*.sql; do \
		echo "  - Applying $$(basename $$file)..."; \
		docker exec -i $(STOVEPIPE_LOCAL_PROJECT)-mysql-queue-1 mysql -uroot -proot submitqueue < $$file 2>&1 | grep -v "Using a password" || true; \
	done
	@echo "✅ Stovepipe schemas applied successfully"

local-runway-start: build-runway-linux ## Start Runway locally (runway + MySQL queue)
	@echo "Starting Runway with compose..."
	@$(COMPOSE) -f $(RUNWAY_COMPOSE_FILE) -p $(RUNWAY_LOCAL_PROJECT) up -d --build --wait
	@echo "Applying queue schema to mysql-queue (no Runway app schema)..."
	@$(MAKE) -s local-init-runway-queue-schema
	@echo ""
	@echo "✅ Runway is running!"
	@echo ""
	@$(COMPOSE) -f $(RUNWAY_COMPOSE_FILE) -p $(RUNWAY_LOCAL_PROJECT) ps
	@echo ""
	@echo "Runway gRPC port: $$(docker port $(RUNWAY_LOCAL_PROJECT)-runway-service-1 8080 2>/dev/null | cut -d: -f2 || echo 'unknown')"
	@echo "MySQL Queue port: $$(docker port $(RUNWAY_LOCAL_PROJECT)-mysql-queue-1 3306 2>/dev/null | cut -d: -f2 || echo 'unknown')"

local-runway-stop: ## Stop Runway service
	@echo "Stopping Runway services..."
	@$(COMPOSE) -f $(RUNWAY_COMPOSE_FILE) -p $(RUNWAY_LOCAL_PROJECT) down
	@echo "Runway services stopped."

local-submitqueue-logs: ## View logs from all running services
	@$(COMPOSE) -f $(COMPOSE_FILE) -f $(PROVIDER_COMPOSE_FILE) -f $(WEB_COMPOSE_FILE) -p $(SUBMITQUEUE_LOCAL_PROJECT) logs -f

local-submitqueue-orchestrator-start: build-submitqueue-orchestrator-linux ## Start Orchestrator service locally (Orchestrator + 2 MySQL databases)
	@echo "Starting Orchestrator with docker-compose..."
	@$(COMPOSE) -f $(ORCHESTRATOR_COMPOSE_FILE) -p $(SUBMITQUEUE_LOCAL_PROJECT) up -d --build --wait
	@echo "Applying database schemas..."
	@$(MAKE) -s local-init-submitqueue-schemas
	@echo ""
	@echo "✅ Orchestrator is running!"
	@echo ""
	@$(COMPOSE) -f $(ORCHESTRATOR_COMPOSE_FILE) -p $(SUBMITQUEUE_LOCAL_PROJECT) ps
	@echo ""
	@echo "Orchestrator gRPC port: $$(docker port $(SUBMITQUEUE_LOCAL_PROJECT)-orchestrator-service-1 8080 2>/dev/null | cut -d: -f2 || echo 'unknown')"
	@echo "MySQL App port:         $$(docker port $(SUBMITQUEUE_LOCAL_PROJECT)-mysql-app-1 3306 2>/dev/null | cut -d: -f2 || echo 'unknown')"
	@echo "MySQL Queue port:       $$(docker port $(SUBMITQUEUE_LOCAL_PROJECT)-mysql-queue-1 3306 2>/dev/null | cut -d: -f2 || echo 'unknown')"

local-submitqueue-orchestrator-stop: ## Stop Orchestrator service
	@echo "Stopping Orchestrator services..."
	@$(COMPOSE) -f $(ORCHESTRATOR_COMPOSE_FILE) -p $(SUBMITQUEUE_LOCAL_PROJECT) down
	@echo "Orchestrator services stopped."

local-submitqueue-ps: ## Show running containers and their ports
	@echo "Running containers and ports:"
	@echo ""
	@$(COMPOSE) -f $(COMPOSE_FILE) -f $(PROVIDER_COMPOSE_FILE) -f $(WEB_COMPOSE_FILE) -p $(SUBMITQUEUE_LOCAL_PROJECT) ps
	@echo ""
	@echo "📡 Service Endpoints:"
	@echo "  Gateway gRPC:      localhost:$$(docker port $(SUBMITQUEUE_LOCAL_PROJECT)-gateway-service-1 8080 2>/dev/null | cut -d: -f2 || echo 'not running')"
	@echo "  Orchestrator gRPC: localhost:$$(docker port $(SUBMITQUEUE_LOCAL_PROJECT)-orchestrator-service-1 8080 2>/dev/null | cut -d: -f2 || echo 'not running')"
	@echo "  Web UX:            http://localhost:$$(docker port $(SUBMITQUEUE_LOCAL_PROJECT)-web-service-1 3000 2>/dev/null | cut -d: -f2 || echo 'not running')"
	@echo ""
	@echo "🗄️  Database Endpoints:"
	@echo "  MySQL App:    localhost:$$(docker port $(SUBMITQUEUE_LOCAL_PROJECT)-mysql-app-1 3306 2>/dev/null | cut -d: -f2 || echo 'not running')"
	@echo "  MySQL Queue:  localhost:$$(docker port $(SUBMITQUEUE_LOCAL_PROJECT)-mysql-queue-1 3306 2>/dev/null | cut -d: -f2 || echo 'not running')"
	@echo ""
	@echo "💡 Usage:"
	@echo "  # Connect to MySQL App DB"
	@echo "  mysql -h127.0.0.1 -P$$(docker port $(SUBMITQUEUE_LOCAL_PROJECT)-mysql-app-1 3306 2>/dev/null | cut -d: -f2 || echo 'PORT') -uroot -proot submitqueue"
	@echo ""
	@echo "  # Call Gateway gRPC"
	@echo "  grpcurl -plaintext -d '{\"message\":\"test\"}' localhost:$$(docker port $(SUBMITQUEUE_LOCAL_PROJECT)-gateway-service-1 8080 2>/dev/null | cut -d: -f2 || echo 'PORT') uber.submitqueue.gateway.SubmitQueueGateway/Ping"
	@echo ""
	@echo "  # View logs"
	@echo "  make local-submitqueue-logs"

local-submitqueue-restart: build-all-linux ## Restart all services (rebuild and restart)
	@echo "Restarting all services..."
	@$(COMPOSE) -f $(COMPOSE_FILE) -f $(PROVIDER_COMPOSE_FILE) -f $(WEB_COMPOSE_FILE) -p $(SUBMITQUEUE_LOCAL_PROJECT) restart
	@echo "Services restarted!"
	@make local-submitqueue-ps

local-submitqueue-start: build-all-linux web-image-load ## Start full stack (PROVIDER=fake|git|github; github needs GITHUB_TOKEN)
	@echo "Starting full stack against provider '$(PROVIDER)' ($(SQ_PROVIDER_CONFIG_DIR))..."
	@test -f "$(SQ_PROVIDER_CONFIG_DIR)/merge.yaml" \
		|| { echo "No such provider '$(PROVIDER)': $(SQ_PROVIDER_CONFIG_DIR)/merge.yaml not found"; exit 2; }
	@test -n "$(PROVIDER_COMPOSE_FILE)" \
		|| { echo "Provider '$(PROVIDER)' has no compose overlay; add PROVIDER_COMPOSE_FILE_$(PROVIDER) to the Makefile"; exit 2; }
	@if [ "$(PROVIDER)" = "git" ]; then \
		$(BAZEL) run //tool/gitsandbox -- -sandbox-dir "$(SQ_GIT_SANDBOX_DIR)" || exit 1; \
	fi
	@# Rootless Docker maps container root to the host user; rootful Docker needs
	@# the host UID:GID explicitly, or the services write files into the sandbox
	@# bind mount that the host user cannot then read or remove. Resolved here
	@# rather than at parse time, so `make help` does not shell out to Docker.
	@set -e; \
	if docker info --format '{{json .SecurityOptions}}' 2>/dev/null | grep -q 'name=rootless'; then \
		export SQ_CONTAINER_USER=0:0; \
	else \
		export SQ_CONTAINER_USER=$$(id -u):$$(id -g); \
	fi; \
	$(COMPOSE) -f $(COMPOSE_FILE) -f $(PROVIDER_COMPOSE_FILE) -f $(WEB_COMPOSE_FILE) -p $(SUBMITQUEUE_LOCAL_PROJECT) up -d --build --wait
	@echo "Applying database schemas..."
	@$(MAKE) -s local-init-submitqueue-schemas
	@echo ""
	@echo "✅ Stack is running against provider '$(PROVIDER)'."
	@echo ""
	@echo "Gateway gRPC port: $$(docker port $(SUBMITQUEUE_LOCAL_PROJECT)-gateway-service-1 8080 2>/dev/null | cut -d: -f2 || echo 'unknown')"
	@echo "Web UX:            http://localhost:$$(docker port $(SUBMITQUEUE_LOCAL_PROJECT)-web-service-1 3000 2>/dev/null | cut -d: -f2 || echo 'unknown')"
	@echo "Web username:      test"
	@echo "Web token:         $(SUBMITQUEUE_WEB_TOKEN)"
	@if [ "$(PROVIDER)" = "git" ]; then \
		echo "Land target:       $(SQ_GIT_SANDBOX_DIR)/sandbox.git"; \
	fi
	@echo ""
	@echo "Generate traffic with:"
	@echo "  make demo-requests"

local-submitqueue-stop: ## Stop the SubmitQueue stack (keeps PROVIDER=git's sandbox; the databases do not survive)
	@echo "Stopping SubmitQueue services..."
	@$(COMPOSE) -f $(COMPOSE_FILE) -f $(PROVIDER_COMPOSE_FILE) -f $(WEB_COMPOSE_FILE) -p $(SUBMITQUEUE_LOCAL_PROJECT) down
	@# Both MySQL services mount anonymous volumes, so `down` detaches them and
	@# the next `up` creates fresh ones. Saying "data preserved" here would be
	@# read as "your requests are still there", which they are not.
	@echo "SubmitQueue services stopped. The databases were on anonymous volumes and start empty next time;"
	@echo "'make local-submitqueue-clean' deletes the orphaned ones."
	@if [ -d "$(SQ_GIT_SANDBOX_DIR)" ]; then \
		echo "Sandbox repository left at $(SQ_GIT_SANDBOX_DIR); remove it with 'make local-submitqueue-clean'."; \
	fi

local-stop: ## Stop every local stack — SubmitQueue, Stovepipe, and Runway
	@echo "Stopping all services..."
	@$(COMPOSE) -f $(COMPOSE_FILE) -f $(PROVIDER_COMPOSE_FILE) -f $(WEB_COMPOSE_FILE) -p $(SUBMITQUEUE_LOCAL_PROJECT) down
	@$(COMPOSE) -f $(STOVEPIPE_COMPOSE_FILE) -p $(STOVEPIPE_LOCAL_PROJECT) down
	@$(COMPOSE) -f $(RUNWAY_COMPOSE_FILE) -p $(RUNWAY_LOCAL_PROJECT) down
	@echo "Services stopped. Anonymous database volumes are not reused on the next start."

local-stovepipe-debug-start: build-stovepipe-linux-debug ## Start Stovepipe under delve in Docker (attach IDE to :2345)
	@echo "Starting Stovepipe service with compose (debug)..."
	@$(COMPOSE) -f $(STOVEPIPE_COMPOSE_FILE) -f $(STOVEPIPE_DEBUG_COMPOSE_FILE) -p $(STOVEPIPE_LOCAL_PROJECT) up -d --build --wait
	@echo "Applying storage and queue schemas..."
	@$(MAKE) -s local-init-stovepipe-schemas
	@echo ""
	@echo "✅ Stovepipe debug is running (delve :2345)!"
	@echo ""
	@$(COMPOSE) -f $(STOVEPIPE_COMPOSE_FILE) -f $(STOVEPIPE_DEBUG_COMPOSE_FILE) -p $(STOVEPIPE_LOCAL_PROJECT) ps
	@echo ""
	@echo "Stovepipe gRPC port: $$(docker port $(STOVEPIPE_LOCAL_PROJECT)-stovepipe-service-1 8080 2>/dev/null | cut -d: -f2 || echo 'unknown')"
	@echo "Delve: 127.0.0.1:2345 — run launch config \"Debug: attach (dlv in docker)\""

local-stovepipe-logs: ## View logs from the running Stovepipe service
	@$(COMPOSE) -f $(STOVEPIPE_COMPOSE_FILE) -p $(STOVEPIPE_LOCAL_PROJECT) logs -f

local-stovepipe-start: build-stovepipe-linux ## Start Stovepipe service (gRPC service + MySQL storage + MySQL queue)
	@echo "Starting Stovepipe service with compose..."
	@$(COMPOSE) -f $(STOVEPIPE_COMPOSE_FILE) -p $(STOVEPIPE_LOCAL_PROJECT) up -d --build --wait
	@echo "Applying storage and queue schemas..."
	@$(MAKE) -s local-init-stovepipe-schemas
	@echo ""
	@echo "✅ Stovepipe service is running!"
	@echo ""
	@$(COMPOSE) -f $(STOVEPIPE_COMPOSE_FILE) -p $(STOVEPIPE_LOCAL_PROJECT) ps
	@echo ""
	@echo "Stovepipe gRPC port: $$(docker port $(STOVEPIPE_LOCAL_PROJECT)-stovepipe-service-1 8080 2>/dev/null | cut -d: -f2 || echo 'unknown')"

local-stovepipe-stop: ## Stop the Stovepipe service
	@echo "Stopping Stovepipe service..."
	@$(COMPOSE) -f $(STOVEPIPE_COMPOSE_FILE) -p $(STOVEPIPE_LOCAL_PROJECT) down
	@echo "Stovepipe service stopped."

# go generate does not walk the module; every tree with a //go:generate directive is listed here.
GO_GENERATE_PACKAGES := \
	./platform/consumer/... \
	./platform/extension/consumergate/... \
	./platform/extension/counter/... \
	./platform/extension/hook/... \
	./platform/extension/messagequeue/... \
	./runway/extension/merger/... \
	./stovepipe/controller/... \
	./stovepipe/core/requestlog/... \
	./stovepipe/extension/buildrunner/... \
	./stovepipe/extension/projectstatus/... \
	./stovepipe/extension/queueconfig/... \
	./stovepipe/extension/sourcecontrol/... \
	./stovepipe/extension/storage/... \
	./submitqueue/core/changeset/... \
	./submitqueue/extension/buildrunner/... \
	./submitqueue/extension/changeprovider/... \
	./submitqueue/extension/conflict/... \
	./submitqueue/extension/queueconfig/... \
	./submitqueue/extension/speculation/... \
	./submitqueue/extension/storage/... \
	./submitqueue/extension/validator/... \
	./submitqueue/gateway/extension/storage/... \
	./submitqueue/orchestrator/extension/storage/...

mocks: ## Generate mock files using mockgen
	@echo "Generating mocks..."
	@$(BAZEL) run @rules_go//go -- generate $(GO_GENERATE_PACKAGES)
	@echo "Mocks generated successfully!"

proto: ## Generate protobuf files from .proto definitions
	@echo "Generating protobuf files with Bazel..."
	@$(BAZEL) build //tool/proto:generated
	@set -e; for pkg in $(PROTO_PACKAGES); do \
	  out=$$(echo $$pkg | tr / _); \
	  mkdir -p $$pkg/protopb; \
	  for f in bazel-bin/tool/proto/$$out/*.go; do \
	    cp -f $$f $$pkg/protopb/$$(basename $$f); \
	    chmod 0644 $$pkg/protopb/$$(basename $$f); \
	  done; \
	done
	@$(BAZEL) run @rules_go//go -- run golang.org/x/tools/cmd/goimports@$(GOIMPORTS_VERSION) -w $(addsuffix /protopb,$(PROTO_PACKAGES))
	@echo "Protobuf files generated successfully!"

# Bazel query helpers
query-deps:
	@$(BAZEL) query 'deps(//service/submitqueue/gateway/server:gateway)'

query-targets:
	@$(BAZEL) query //...

run-client-submitqueue-gateway: ## Run the gateway client (ARGS="land -queue q -pr <url>"; defaults to a ping)
	@$(BAZEL) run //service/submitqueue/gateway/client:gateway -- \
		-addr $(or $(SERVER_ADDR),localhost:8081) \
		$(if $(ARGS),$(ARGS),ping -message "$(or $(MESSAGE),ping)")

run-client-submitqueue-orchestrator: ## Run the orchestrator client against a running orchestrator (SERVER_ADDR, MESSAGE)
	@$(BAZEL) run //service/submitqueue/orchestrator/client:orchestrator -- -addr $(or $(SERVER_ADDR),localhost:8082) -message "$(or $(MESSAGE),ping)"

run-client-stovepipe: ## Run the Stovepipe client against a running Stovepipe (SERVER_ADDR, MESSAGE)
	@$(BAZEL) run //service/stovepipe/client:stovepipe -- -addr $(or $(SERVER_ADDR),localhost:8083) -message "$(or $(MESSAGE),ping)"

run-client-runway: ## Run the Runway client against a running Runway (SERVER_ADDR, MESSAGE)
	@$(BAZEL) run //service/runway/client:runway -- -addr $(or $(SERVER_ADDR),localhost:8086) -message "$(or $(MESSAGE),ping)"

run-queue-admin: ## Run queue-admin CLI (use ARGS to pass arguments, e.g. make run-queue-admin ARGS="list-topics")
	@$(BAZEL) run //platform/extension/messagequeue/mysql/ctl -- $(ARGS)

test: ## Run unit tests
	@echo "Running unit tests..."
	@$(BAZEL) test //... --test_tag_filters=-manual,-integration --build_tests_only

test-no-cache: ## Run unit tests without cache (force re-run)
	@echo "Running unit tests (no cache)..."
	@$(BAZEL) test //... --test_tag_filters=-manual,-integration --nocache_test_results

test-race: ## Run unit tests with the race detector (not run in CI)
	@echo "Running unit tests with race detector..."
	@# build_tests_only keeps the cross-compiled *_linux binaries out of the
	@# build: they are cgo-free, and race instrumentation requires cgo.
	@$(BAZEL) test //... --test_tag_filters=-manual,-integration --build_tests_only --@rules_go//go/config:race

tidy: tidy-go tidy-bazel ## Run go mod tidy and bazel mod tidy

tidy-bazel: ## Run bazel mod tidy
	@echo "Running bazel mod tidy..."
	@$(BAZEL) mod tidy

tidy-go: ## Run go mod tidy
	@echo "Running go mod tidy..."
	@$(BAZEL) run @rules_go//go -- mod tidy -e

web-build: ## Build the web packages and deployable Next.js image with Bazel
	@$(BAZEL) build //web/submitqueue:pkg //web/service/submitqueue:image

web-check: ## Run web generation, packaging, lint, type, unit, and image checks with Bazel
	@$(BAZEL) test //web:check --test_output=errors
	@$(BAZEL) build //web/service/submitqueue:image

web-e2e-test: ## Run the Bazel-managed real-stack Playwright and axe web test
	@$(BAZEL) test //web/test/e2e:web_test --test_output=errors

web-image-load: ## Build and load the deployable web image into Docker with Bazel (also tagged with SQ_DOCKER_IMAGE_PREFIX)
	@$(BAZEL) run //web/service/submitqueue:image_load
	@if [ -n "$$SQ_DOCKER_IMAGE_PREFIX" ] && [ "$$SQ_DOCKER_IMAGE_PREFIX" != "submitqueue" ]; then \
		docker tag submitqueue-web-service:latest "$$SQ_DOCKER_IMAGE_PREFIX-web-service:latest"; \
	fi

web-install: ## Install the pinned web workspace dependencies
	@corepack pnpm@10.17.1 --dir web install --frozen-lockfile

web-proto: ## Regenerate the committed TypeScript protobuf API with Bazel
	@$(BAZEL) run //web/api:generate

help: ## Show this help message
	@echo "Available targets:"
	@echo ""
	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-30s\033[0m %s\n", $$1, $$2}'