Makefile

# Load local overrides (gitignored) — e.g. KAGENT_HELM_EXTRA_ARGS=-f helm/kagent/values.local.yaml
-include .env

# Image configuration
DOCKER_REGISTRY ?= localhost:5001
BASE_IMAGE_REGISTRY ?= cgr.dev
DOCKER_REPO ?= kagent-dev/kagent
HELM_REPO ?= oci://ghcr.io/kagent-dev
HELM_DIST_FOLDER ?= dist

BUILD_DATE := $(shell date -u '+%Y-%m-%d')
GIT_COMMIT := $(shell git rev-parse --short HEAD || echo "unknown")
VERSION ?= $(shell git describe --tags --always 2>/dev/null | grep v || echo "v0.0.0-$(GIT_COMMIT)")

# Local architecture detection to build for the current platform
LOCALARCH ?= $(shell uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/')

KUBECONFIG_PERM ?= $(shell \
  if [ "$$(uname -s | tr '[:upper:]' '[:lower:]')" = "darwin" ]; then \
    stat -f "%Lp" ~/.kube/config; \
  else \
    stat -c "%a" ~/.kube/config; \
  fi)


# Container runtime: "docker" (default) or "podman".
# Set CONTAINER_RUNTIME=podman to use Podman for all container operations.
CONTAINER_RUNTIME ?= docker

# Buildx configuration
BUILDKIT_VERSION = v0.23.0
BUILDX_NO_DEFAULT_ATTESTATIONS=1
BUILDX_BUILDER_NAME ?= kagent-builder-$(BUILDKIT_VERSION)

ifeq ($(CONTAINER_RUNTIME),podman)
  DOCKER_BUILDER ?= $(CONTAINER_RUNTIME) build
  DOCKER_BUILD_ARGS ?= --platform linux/$(LOCALARCH)
  # Podman needs a separate push step (no --push on build).
  # --tls-verify=false is needed for local insecure registries (e.g. kind-registry).
  # Override PODMAN_TLS_VERIFY=true when pushing to a remote TLS registry.
  PODMAN_TLS_VERIFY ?= false
  DOCKER_PUSH = $(CONTAINER_RUNTIME) push --tls-verify=$(PODMAN_TLS_VERIFY)
else
  DOCKER_BUILDER ?= $(CONTAINER_RUNTIME) buildx build
  DOCKER_BUILD_ARGS ?= --push --platform linux/$(LOCALARCH)
  # Docker buildx --push handles push inline; no separate push step needed.
  DOCKER_PUSH = @true
endif

KIND_CLUSTER_NAME ?= kagent
KIND_IMAGE_VERSION ?= 1.35.0

CONTROLLER_IMAGE_NAME ?= controller
UI_IMAGE_NAME ?= ui
KAGENT_ADK_IMAGE_NAME ?= kagent-adk
GOLANG_ADK_IMAGE_NAME ?= golang-adk

CONTROLLER_IMAGE_TAG ?= $(VERSION)
UI_IMAGE_TAG ?= $(VERSION)
KAGENT_ADK_IMAGE_TAG ?= $(VERSION)
GOLANG_ADK_IMAGE_TAG ?= $(VERSION)
CONTROLLER_IMG ?= $(DOCKER_REGISTRY)/$(DOCKER_REPO)/$(CONTROLLER_IMAGE_NAME):$(CONTROLLER_IMAGE_TAG)
UI_IMG ?= $(DOCKER_REGISTRY)/$(DOCKER_REPO)/$(UI_IMAGE_NAME):$(UI_IMAGE_TAG)
KAGENT_ADK_IMG ?= $(DOCKER_REGISTRY)/$(DOCKER_REPO)/$(KAGENT_ADK_IMAGE_NAME):$(KAGENT_ADK_IMAGE_TAG)
GOLANG_ADK_IMG ?= $(DOCKER_REGISTRY)/$(DOCKER_REPO)/$(GOLANG_ADK_IMAGE_NAME):$(GOLANG_ADK_IMAGE_TAG)

#take from go/go.mod
AWK ?= $(shell command -v gawk || command -v awk)
TOOLS_GO_VERSION ?= $(shell $(AWK) '/^go / { print $$2 }' go/go.mod)
export GOTOOLCHAIN=go$(TOOLS_GO_VERSION)

# Version information for the build
LDFLAGS := -X github.com/$(DOCKER_REPO)/go/core/internal/version.Version=$(VERSION) \
           -X github.com/$(DOCKER_REPO)/go/core/internal/version.GitCommit=$(GIT_COMMIT) \
           -X github.com/$(DOCKER_REPO)/go/core/internal/version.BuildDate=$(BUILD_DATE)

#tools versions
TOOLS_UV_VERSION ?= 0.10.4
TOOLS_NODE_VERSION ?= 24
TOOLS_PYTHON_VERSION ?= 3.13
BUF_VERSION ?= v1.72.0
BUF := go run github.com/bufbuild/buf/cmd/buf@$(BUF_VERSION)

# build args
TOOLS_IMAGE_BUILD_ARGS =  --build-arg VERSION=$(VERSION)
TOOLS_IMAGE_BUILD_ARGS += --build-arg LDFLAGS="$(LDFLAGS)"
TOOLS_IMAGE_BUILD_ARGS += --build-arg DOCKER_REPO=$(DOCKER_REPO)
TOOLS_IMAGE_BUILD_ARGS += --build-arg DOCKER_REGISTRY=$(DOCKER_REGISTRY)
TOOLS_IMAGE_BUILD_ARGS += --build-arg BASE_IMAGE_REGISTRY=$(BASE_IMAGE_REGISTRY)
TOOLS_IMAGE_BUILD_ARGS += --build-arg TOOLS_GO_VERSION=$(TOOLS_GO_VERSION)
TOOLS_IMAGE_BUILD_ARGS += --build-arg TOOLS_UV_VERSION=$(TOOLS_UV_VERSION)
TOOLS_IMAGE_BUILD_ARGS += --build-arg TOOLS_PYTHON_VERSION=$(TOOLS_PYTHON_VERSION)
TOOLS_IMAGE_BUILD_ARGS += --build-arg TOOLS_NODE_VERSION=$(TOOLS_NODE_VERSION)


##@ General

# The help target prints out all targets with their descriptions organized
# beneath their categories. The categories are represented by '##@' and the
# target descriptions by '##'. The awk command is responsible for reading the
# entire set of makefiles included in this invocation, looking for lines of the
# file as xyz: ## something, and then pretty-format the target and help. Then,
# if there's a line with ##@ something, that gets pretty-printed as a category.
# More info on the usage of ANSI control characters for terminal formatting:
# https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters
# More info on the awk command:
# http://linuxcommand.org/lc3_adv_awk.php

.PHONY: help
help: ## Display this help.
	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-24s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)

.PHONY: print-tools-versions
print-tools-versions: ## Print tools versions
	@echo "VERSION      : $(VERSION)"
	@echo "Tools Go     : $(TOOLS_GO_VERSION)"
	@echo "Tools UV     : $(TOOLS_UV_VERSION)"
	@echo "Tools Node   : $(TOOLS_NODE_VERSION)"
	@echo "Tools Istio  : $(TOOLS_ISTIO_VERSION)"
	@echo "Tools Argo CD: $(TOOLS_ARGO_CD_VERSION)"

##@ Protobuf

.PHONY: proto-generate
proto-generate: ## Generate Go, TypeScript, and Python protobuf clients and servers
	cd proto && $(BUF) generate

.PHONY: proto-lint
proto-lint: ## Lint repository-owned protobuf schemas
	cd proto && $(BUF) lint

.PHONY: proto-breaking
proto-breaking: ## Check protobuf compatibility against the target branch (default: main)
	@if git cat-file -e "$(PROTO_BREAKING_BRANCH):proto/buf.yaml" 2>/dev/null; then \
		$(BUF) breaking proto --against ".git#branch=$(PROTO_BREAKING_BRANCH),subdir=proto"; \
	else \
		echo "No protobuf module on $(PROTO_BREAKING_BRANCH); skipping first-release breaking check"; \
	fi

PROTO_BREAKING_BRANCH ?= main
PROTO_GENERATED_PATHS := go/api/gen ui/src/generated python/packages/kagent-proto/src/kagent

.PHONY: proto-check
proto-check: proto-lint proto-generate ## Regenerate protobuf artifacts and fail when committed output drifts
	@if test -n "$$(git status --porcelain -- $(PROTO_GENERATED_PATHS))"; then \
		echo "Generated protobuf files are out of date:"; \
		git status --short -- $(PROTO_GENERATED_PATHS); \
		exit 1; \
	fi

##@ Git

.PHONY: init-git-hooks
init-git-hooks:  ## Use the tracked version of Git hooks from this repo
	git config core.hooksPath .githooks
	echo "Git hooks initialized"

# KMCP
KMCP_ENABLED ?= true
KMCP_VERSION ?= $(shell $(AWK) '/github\.com\/kagent-dev\/kmcp/ { print substr($$2, 2) }' go/go.mod) # KMCP version defaults to what's referenced in go.mod

# Substrate
SUBSTRATE_ENABLED ?= false
SUBSTRATE_VERSION ?= $(shell $(AWK) '/github\.com\/kagent-dev\/substrate/ { print substr($$5, 2) }' go/go.mod) # Substrate version defaults to the replace target in go.mod
SUBSTRATE_REPO ?= oci://ghcr.io/kagent-dev/substrate/helm # Override for local dev when consuming a locally-published chart, e.g. oci://localhost:5001/kagent-dev/substrate/helm

HELM_ACTION=upgrade --install

# Helm chart variables
KAGENT_DEFAULT_MODEL_PROVIDER ?= openAI


##@ Build

.PHONY: check-api-key
check-api-key: ## Validate required API key for the configured model provider
	@if [ "$(KAGENT_DEFAULT_MODEL_PROVIDER)" = "openAI" ]; then \
		if [ -z "$(OPENAI_API_KEY)" ]; then \
			echo "Error: OPENAI_API_KEY environment variable is not set for OpenAI provider"; \
			echo "Please set it with: export OPENAI_API_KEY=your-api-key"; \
			exit 1; \
		fi; \
	elif [ "$(KAGENT_DEFAULT_MODEL_PROVIDER)" = "anthropic" ]; then \
		if [ -z "$(ANTHROPIC_API_KEY)" ]; then \
			echo "Error: ANTHROPIC_API_KEY environment variable is not set for Anthropic provider"; \
			echo "Please set it with: export ANTHROPIC_API_KEY=your-api-key"; \
			exit 1; \
		fi; \
	elif [ "$(KAGENT_DEFAULT_MODEL_PROVIDER)" = "azureOpenAI" ]; then \
		if [ -z "$(AZURE_OPENAI_API_KEY)" ]; then \
			echo "Error: AZURE_OPENAI_API_KEY environment variable is not set for Azure OpenAI provider"; \
			echo "Please set it with: export AZURE_OPENAI_API_KEY=your-api-key"; \
			exit 1; \
		fi; \
	elif [ "$(KAGENT_DEFAULT_MODEL_PROVIDER)" = "gemini" ]; then \
		if [ -z "$(GOOGLE_API_KEY)" ]; then \
			echo "Error: GOOGLE_API_KEY environment variable is not set for Gemini provider"; \
			echo "Please set it with: export GOOGLE_API_KEY=your-api-key"; \
			exit 1; \
		fi; \
	elif [ "$(KAGENT_DEFAULT_MODEL_PROVIDER)" = "ollama" ]; then \
		echo "Note: Ollama provider does not require an API key"; \
	else \
		echo "Warning: Unknown model provider '$(KAGENT_DEFAULT_MODEL_PROVIDER)'. Skipping API key check."; \
	fi

.PHONY: buildx-create
buildx-create: ## Create or reuse the buildx builder instance
ifeq ($(CONTAINER_RUNTIME),podman)
	@echo "Podman detected; skipping buildx builder setup (using built-in buildx)."
else
	$(CONTAINER_RUNTIME) buildx inspect $(BUILDX_BUILDER_NAME) 2>&1 > /dev/null || \
	$(CONTAINER_RUNTIME) buildx create --name $(BUILDX_BUILDER_NAME) --platform linux/amd64,linux/arm64 --driver docker-container --use --driver-opt network=host || true
	$(CONTAINER_RUNTIME) buildx use $(BUILDX_BUILDER_NAME) || true
endif

.PHONY: build-all
build-all: ## Build all images for amd64+arm64 without pushing (outputs to /dev/null for CI validation)
build-all: BUILD_ARGS ?= --progress=plain --builder $(BUILDX_BUILDER_NAME) --platform linux/amd64,linux/arm64 --output type=tar,dest=/dev/null
build-all: proto-generate buildx-create
	$(DOCKER_BUILDER) $(BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) -f go/Dockerfile     ./go
	$(DOCKER_BUILDER) $(BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) -f ui/Dockerfile     ./ui
	$(DOCKER_BUILDER) $(BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) -f python/Dockerfile ./python

.PHONY: build
build: ## Build and push all component images
build: buildx-create build-ui build-kagent-adk build-golang-adk build-controller
	@echo "Build completed successfully."
	@echo "Controller Image: $(CONTROLLER_IMG)"
	@echo "UI Image: $(UI_IMG)"
	@echo "Kagent ADK Image: $(KAGENT_ADK_IMG)"
	@echo "Golang ADK Image: $(GOLANG_ADK_IMG)"

.PHONY: build-monitor
build-monitor: ## Watch BuildKit process list inside the buildx container
build-monitor: buildx-create
ifeq ($(CONTAINER_RUNTIME),podman)
	@echo "build-monitor is not supported with Podman (no external buildkit container)"
else
	watch $(CONTAINER_RUNTIME) exec -t  buildx_buildkit_$(BUILDX_BUILDER_NAME)0  ps
endif

.PHONY: build-cli
build-cli: ## Build the kagent CLI (cross-compiled via go sub-make)
build-cli: proto-generate
	make -C go build

.PHONY: build-cli-local
build-cli-local: ## Build the kagent CLI binary for the local machine
build-cli-local: proto-generate
	make -C go clean
	make -C go core/bin/kagent-local

.PHONY: build-img-versions
build-img-versions: ## Print the fully-qualified image tags for all components
	@echo controller=$(CONTROLLER_IMG)
	@echo ui=$(UI_IMG)
	@echo kagent-adk=$(KAGENT_ADK_IMG)
	@echo golang-adk=$(GOLANG_ADK_IMG)

.PHONY: controller-manifests
controller-manifests: ## Regenerate CRD manifests and copy them into the Helm chart
	make -C go manifests
	cp go/api/config/crd/bases/* helm/kagent-crds/templates/

.PHONY: build-controller
build-controller: ## Build and push the API v2 controller image
build-controller: buildx-create
	$(DOCKER_BUILDER) $(DOCKER_BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) \
		--build-arg BUILD_PACKAGE=core/cmd/controller-v2/main.go \
		-t $(CONTROLLER_IMG) -f go/Dockerfile ./go
	$(DOCKER_PUSH) $(CONTROLLER_IMG)

.PHONY: build-ui
build-ui: ## Build and push the UI image
build-ui: proto-generate buildx-create
	$(DOCKER_BUILDER) $(DOCKER_BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) -t $(UI_IMG) -f ui/Dockerfile ./ui
	$(DOCKER_PUSH) $(UI_IMG)

.PHONY: build-kagent-adk
build-kagent-adk: ## Build and push the Python kagent ADK image
build-kagent-adk: proto-generate buildx-create
	$(DOCKER_BUILDER) $(DOCKER_BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) -t $(KAGENT_ADK_IMG) -f python/Dockerfile ./python
	$(DOCKER_PUSH) $(KAGENT_ADK_IMG)

.PHONY: build-golang-adk
build-golang-adk: ## Build and push the Go ADK image
build-golang-adk: proto-generate buildx-create
	$(DOCKER_BUILDER) $(DOCKER_BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) --build-arg BUILD_PACKAGE=adk/cmd/main.go -t $(GOLANG_ADK_IMG) -f go/Dockerfile ./go
	$(DOCKER_PUSH) $(GOLANG_ADK_IMG)

.PHONY: push
push: ## Push all component images (controller, ui, ADKs)
push: push-controller push-ui push-kagent-adk push-golang-adk


##@ Testing

.PHONY: lint
lint: ## Run linters for Go and Python
	make -C go lint
	make -C python lint


##@ Cluster

.PHONY: create-kind-cluster

create-kind-cluster: ## Create a local kind cluster with MetalLB
	CONTAINER_RUNTIME=$(CONTAINER_RUNTIME) KIND_CLUSTER_NAME=$(KIND_CLUSTER_NAME) KIND_IMAGE_VERSION=$(KIND_IMAGE_VERSION) bash ./scripts/kind/setup-kind.sh
	CONTAINER_RUNTIME=$(CONTAINER_RUNTIME) KIND_CLUSTER_NAME=$(KIND_CLUSTER_NAME) bash ./scripts/kind/setup-metallb.sh

.PHONY: use-kind-cluster
use-kind-cluster: ## Merge kind kubeconfig and set kagent as the default namespace
	kind get kubeconfig --name $(KIND_CLUSTER_NAME) > /tmp/kind-config
	KUBECONFIG=~/.kube/config:/tmp/kind-config kubectl config view --merge --flatten > ~/.kube/config.tmp && mv ~/.kube/config.tmp ~/.kube/config && chmod $(KUBECONFIG_PERM) ~/.kube/config
	kubectl --context kind-$(KIND_CLUSTER_NAME) create namespace kagent || true
	kubectl config set-context kind-$(KIND_CLUSTER_NAME) --namespace kagent || true

.PHONY: delete-kind-cluster
delete-kind-cluster: ## Delete the local kind cluster
	kind delete cluster --name $(KIND_CLUSTER_NAME)


##@ Helm

.PHONY: helm-cleanup
helm-cleanup: ## Remove packaged Helm charts from the dist folder
	rm -f ./$(HELM_DIST_FOLDER)/*.tgz

.PHONY: helm-test
helm-test: ## Render Helm templates for all providers and run helm unittest
helm-test: helm-version
	mkdir -p tmp
	echo $$(helm template kagent ./helm/kagent/ --namespace kagent --set providers.default=ollama																	| tee tmp/ollama.yaml 		| grep ^kind: | wc -l)
	echo $$(helm template kagent ./helm/kagent/ --namespace kagent --set providers.default=openAI       --set providers.openAI.apiKey=your-openai-api-key 			| tee tmp/openAI.yaml 		| grep ^kind: | wc -l)
	echo $$(helm template kagent ./helm/kagent/ --namespace kagent --set providers.default=anthropic    --set providers.anthropic.apiKey=your-anthropic-api-key 	| tee tmp/anthropic.yaml 	| grep ^kind: | wc -l)
	echo $$(helm template kagent ./helm/kagent/ --namespace kagent --set providers.default=azureOpenAI  --set providers.azureOpenAI.apiKey=your-openai-api-key		| tee tmp/azureOpenAI.yaml	| grep ^kind: | wc -l)
	echo $$(helm template kagent ./helm/kagent/ --namespace kagent --set providers.default=gemini       --set providers.gemini.apiKey=your-gemini-api-key 			| tee tmp/gemini.yaml 		| grep ^kind: | wc -l)
	helm plugin ls | grep unittest || helm plugin install https://github.com/helm-unittest/helm-unittest.git
	helm unittest helm/kagent

.PHONY: helm-tools
helm-tools: ## Package all tool Helm charts into the dist folder
	VERSION=$(VERSION) envsubst < helm/tools/grafana-mcp/Chart-template.yaml > helm/tools/grafana-mcp/Chart.yaml
	helm package -d $(HELM_DIST_FOLDER) helm/tools/grafana-mcp

.PHONY: helm-version
helm-version: ## Stamp chart versions, update dependencies, and package kagent + kagent-crds
helm-version: helm-cleanup helm-tools
	VERSION=$(VERSION) KMCP_VERSION=$(KMCP_VERSION) SUBSTRATE_VERSION=$(SUBSTRATE_VERSION) SUBSTRATE_REPO=$(SUBSTRATE_REPO) envsubst < helm/kagent-crds/Chart-template.yaml > helm/kagent-crds/Chart.yaml
	VERSION=$(VERSION) KMCP_VERSION=$(KMCP_VERSION) SUBSTRATE_VERSION=$(SUBSTRATE_VERSION) SUBSTRATE_REPO=$(SUBSTRATE_REPO) envsubst < helm/kagent/Chart-template.yaml > helm/kagent/Chart.yaml
	helm dependency update helm/kagent
	helm dependency update helm/kagent-crds
	helm package -d $(HELM_DIST_FOLDER) helm/kagent-crds
	helm package -d $(HELM_DIST_FOLDER) helm/kagent

.PHONY: helm-install-provider
helm-install-provider: ## Install or upgrade kagent-crds and kagent Helm releases on the kind cluster
helm-install-provider: helm-version check-api-key
	helm $(HELM_ACTION) kagent-crds helm/kagent-crds \
		--namespace kagent \
		--create-namespace \
		--history-max 2    \
		--timeout 5m 			\
		--kube-context kind-$(KIND_CLUSTER_NAME) \
		--wait \
		--set kmcp.enabled=$(KMCP_ENABLED)
	helm $(HELM_ACTION) kagent helm/kagent \
		--namespace kagent \
		--create-namespace \
		--history-max 2    \
		--timeout 5m       \
		--kube-context kind-$(KIND_CLUSTER_NAME) \
		--wait \
		--set ui.service.type=LoadBalancer \
		--set registry=$(DOCKER_REGISTRY) \
		--set imagePullPolicy=Always \
		--set tag=$(VERSION) \
		--set controller.loglevel=debug \
		--set controller.image.pullPolicy=Always \
		--set ui.image.pullPolicy=Always \
		--set controller.service.type=LoadBalancer \
		--set providers.openAI.apiKey=$(OPENAI_API_KEY) \
		--set providers.azureOpenAI.apiKey=$(AZURE_OPENAI_API_KEY) \
		--set providers.anthropic.apiKey=$(ANTHROPIC_API_KEY) \
		--set providers.gemini.apiKey=$(GOOGLE_API_KEY) \
		--set providers.default=$(KAGENT_DEFAULT_MODEL_PROVIDER) \
		--set kmcp.enabled=$(KMCP_ENABLED) \
		--set kmcp.image.tag=$(KMCP_VERSION) \
		--set database.postgres.bundled.image.repository=pgvector \
		--set database.postgres.bundled.image.name=pgvector \
		--set database.postgres.bundled.image.tag=pg18-trixie \
		--set database.postgres.vectorEnabled=true \
		$(KAGENT_HELM_EXTRA_ARGS)

.PHONY: helm-install
helm-install: ## Build all images then install kagent onto the kind cluster
helm-install: build
helm-install: helm-install-provider

.PHONY: helm-test-install
helm-test-install: ## Dry-run helm install to validate chart rendering (pipe to tee for inspection)
helm-test-install: HELM_ACTION+="--dry-run"
helm-test-install: helm-install-provider

.PHONY: helm-uninstall
helm-uninstall: ## Uninstall kagent and kagent-crds Helm releases from the kind cluster
	helm uninstall kagent --namespace kagent --kube-context kind-$(KIND_CLUSTER_NAME) --wait
	helm uninstall kagent-crds --namespace kagent --kube-context kind-$(KIND_CLUSTER_NAME) --wait

# Upgrade test targets install the previous released kagent chart from the public
# OCI registry, build the current images, then run the assertions in
# go/core/test/upgrade. These tests are deliberately kept out of test/e2e: they
# mutate the cluster (upgrade then reverse-migrate it) and so cannot share the
# e2e suite's cluster. The Go test performs the actual upgrade to the current
# build by invoking `make helm-install-provider`. UPGRADE_FROM_VERSION defaults to
# the latest version reachable from HEAD (scripts/upgrade-from-version.sh); CI runs
# this against two targets via a matrix — that adjacent version and the previous
# release line's latest published version (scripts/prev-stable-version.sh) — and
# you can pin either locally, e.g.
# `UPGRADE_FROM_VERSION=$$(./scripts/prev-stable-version.sh)`.
# The previous install pins the bundled Postgres image to whatever the
# upgrade-from release's own install target shipped (resolved inside
# install-previous-release), so the baseline matches how that release actually
# runs rather than a hardcoded guess; the upgrade then exercises the real
# app/migration (and any DB image) change between that release and the current
# build.
#
# Prerequisite (provided by CI as a separate step; run it locally first): a kind
# cluster (make create-kind-cluster). agent-sandbox is not required — the
# controller tolerates the missing CRD and these tests create no SandboxAgents.
#
# Lazily evaluated and referenced only by the upgrade targets below, so unrelated
# make invocations never run the resolver; CI passes UPGRADE_FROM_VERSION
# explicitly (per matrix leg), which bypasses the script entirely.
UPGRADE_FROM_VERSION ?= $(shell ./scripts/upgrade-from-version.sh)

.PHONY: install-previous-release
install-previous-release: ## Install the previous released kagent + kagent-crds charts from the public OCI registry
	# Abort early (rather than let helm fail confusingly) if the upgrade-from
	# version could not be resolved.
	[ -n "$(UPGRADE_FROM_VERSION)" ] || { echo "UPGRADE_FROM_VERSION is empty; set it explicitly or ensure git tags are fetched." >&2; exit 1; }
	@echo "=== Installing previous release: $(UPGRADE_FROM_VERSION) ==="
	helm upgrade --install kagent-crds $(HELM_REPO)/kagent/helm/kagent-crds \
		--version $(UPGRADE_FROM_VERSION) \
		--namespace kagent --create-namespace \
		--kube-context kind-$(KIND_CLUSTER_NAME) \
		--timeout 5m --wait
	# The bundled-Postgres image is selected by the install target's --set flags,
	# not by the chart defaults (the chart ships a non-vector image). So the
	# previous install must use the exact pins the upgrade-from release shipped —
	# otherwise the baseline DB would differ from how that release actually runs,
	# and the upgrade would conflate a DB swap with the migration change under
	# test. Read those flags straight from that release's own helm-install-provider
	# target (via its tagged Makefile) rather than hardcoding values that drift as
	# the bundled image changes. Resolved here in the recipe so the `git show` runs
	# only when this target runs, and so the flags can be validated before use
	# (they must be literal — a future release that parameterizes them with a
	# make/env variable would be rejected rather than passed to helm verbatim).
	@set -e; \
	db_flags="$$(git show v$(UPGRADE_FROM_VERSION):Makefile 2>/dev/null | grep -oE '\-\-set[[:space:]]+database\.postgres\.[^[:space:]\\]+' | tr '\n' ' ')"; \
	[ -n "$$db_flags" ] || { echo "Could not read bundled-Postgres --set flags from v$(UPGRADE_FROM_VERSION):Makefile; the upgrade-from release's install target may have moved or renamed them." >&2; exit 1; }; \
	case "$$db_flags" in *'$$'*|*'('*|*'{'*) echo "Bundled-Postgres --set flags from v$(UPGRADE_FROM_VERSION):Makefile contain an unexpanded variable and cannot be passed to helm verbatim: $$db_flags" >&2; exit 1;; esac; \
	echo "    bundled-Postgres flags (from v$(UPGRADE_FROM_VERSION) install target): $$db_flags"; \
	helm upgrade --install kagent $(HELM_REPO)/kagent/helm/kagent \
		--version $(UPGRADE_FROM_VERSION) \
		--namespace kagent --create-namespace \
		--kube-context kind-$(KIND_CLUSTER_NAME) \
		--timeout 5m --wait \
		--set ui.service.type=LoadBalancer \
		--set controller.service.type=LoadBalancer \
		--set providers.default=openAI \
		--set providers.openAI.apiKey="$${OPENAI_API_KEY:-test}" \
		$$db_flags $(UPGRADE_PREV_EXTRA_ARGS)

# run-upgrade-tests installs the previous release, builds the current images, and
# runs the DB-layer upgrade scenario in TestUpgrade: seed -> upgrade -> controller
# rollout (no crash) -> data survival -> schema-equivalence (upgraded == clean
# install) -> reverse schema to target (down files) + data survival. At each
# state it also runs a version-matched invoke e2e slice (TestE2EInvokeInlineAgent)
# so the serving controller's real query paths are exercised, not just psql: the
# HEAD tree post-upgrade, and the previous release's own tree (a git worktree at
# its tag, in .upgrade-prev) for the old-code-against-new-schema and post-rollback
# states. KAGENT_LOCAL_HOST (kind gateway IP) lets the agent reach the in-process
# mock LLM; without it the invoke slices self-skip and only the DB round-trip runs.
# Prerequisite (provided by CI as a separate step; run it locally first): a kind
# cluster (make create-kind-cluster). The controller tolerates the missing
# agent-sandbox CRD (the owned-resource watch is skipped), and these tests create
# no SandboxAgents, so agent-sandbox is not required.
.PHONY: announce-upgrade-from
announce-upgrade-from: ## Print the upgrade-from -> to versions (runs before the build so it is clear up front)
	@echo "=== Upgrade test: FROM $(UPGRADE_FROM_VERSION) TO $(VERSION) — building current images next ==="

.PHONY: run-upgrade-tests
run-upgrade-tests: announce-upgrade-from build install-previous-release ## Install the previous release, build current images, and run the upgrade + version-matched invoke tests
	@echo "=== Upgrade test: $(UPGRADE_FROM_VERSION) -> $(VERSION) (registry=$(DOCKER_REGISTRY)) ==="
	@set -e; \
	git worktree remove --force "$(CURDIR)/.upgrade-prev" 2>/dev/null || true; \
	git worktree add --detach "$(CURDIR)/.upgrade-prev" "v$(UPGRADE_FROM_VERSION)"; \
	trap 'git worktree remove --force "$(CURDIR)/.upgrade-prev" 2>/dev/null || true' EXIT; \
	kind_gw="$$($(CONTAINER_RUNTIME) network inspect kind -f '{{range .IPAM.Config}}{{if .Gateway}}{{.Gateway}}{{"\n"}}{{end}}{{end}}' | grep -E '^[0-9]+\.' | head -1)"; \
	echo "kind gateway (KAGENT_LOCAL_HOST): $$kind_gw"; \
	cd go && \
	RUN_UPGRADE_TESTS=true \
	REPO_ROOT=$(CURDIR) \
	PREV_E2E_DIR=$(CURDIR)/.upgrade-prev \
	KAGENT_LOCAL_HOST="$$kind_gw" \
	UPGRADE_FROM_VERSION=$(UPGRADE_FROM_VERSION) \
	VERSION=$(VERSION) \
	DOCKER_REGISTRY=$(DOCKER_REGISTRY) \
	KIND_CLUSTER_NAME=$(KIND_CLUSTER_NAME) \
	OPENAI_API_KEY="$${OPENAI_API_KEY:-test}" \
	go test ./core/test/upgrade -run TestUpgrade -count=1 -timeout=45m -v

# The target-specific UPGRADE_PREV_EXTRA_ARGS propagates to the
# install-previous-release prerequisite, so the previous release comes up with 2
# controller replicas (needed to observe the old-code/new-schema rollout window).
.PHONY: run-rolling-upgrade-tests
run-rolling-upgrade-tests: UPGRADE_PREV_EXTRA_ARGS = --set controller.replicas=2
run-rolling-upgrade-tests: announce-upgrade-from build install-previous-release ## Install the previous release with 2 controller replicas, build the current images, and run the rolling upgrade e2e test
	@echo "=== Rolling upgrade test: $(UPGRADE_FROM_VERSION) -> $(VERSION) (registry=$(DOCKER_REGISTRY)) ==="
	cd go && \
	RUN_ROLLING_UPGRADE_TESTS=true \
	REPO_ROOT=$(CURDIR) \
	UPGRADE_FROM_VERSION=$(UPGRADE_FROM_VERSION) \
	VERSION=$(VERSION) \
	DOCKER_REGISTRY=$(DOCKER_REGISTRY) \
	KIND_CLUSTER_NAME=$(KIND_CLUSTER_NAME) \
	OPENAI_API_KEY="$${OPENAI_API_KEY:-test}" \
	go test ./core/test/upgrade -run TestRollingUpgradeCompatibility -count=1 -timeout=20m -v

.PHONY: helm-publish
helm-publish: ## Package and push all Helm charts to the OCI registry
helm-publish: helm-version
	helm push ./$(HELM_DIST_FOLDER)/kagent-crds-$(VERSION).tgz $(HELM_REPO)/kagent/helm
	helm push ./$(HELM_DIST_FOLDER)/kagent-$(VERSION).tgz $(HELM_REPO)/kagent/helm

##@ Dev

.PHONY: kagent-cli-install
kagent-cli-install: ## Build CLI locally, install kagent, and open the dashboard
kagent-cli-install: use-kind-cluster build-cli-local helm-version helm-install-provider
	KAGENT_HELM_REPO=./helm/ ./go/core/bin/kagent-local dashboard

.PHONY: kagent-cli-port-forward
kagent-cli-port-forward: ## Port-forward the kagent controller API to localhost:8083
kagent-cli-port-forward: use-kind-cluster
	@echo "Port forwarding to kagent CLI..."
	kubectl --context kind-$(KIND_CLUSTER_NAME) port-forward -n kagent service/kagent-controller 8083:8083

.PHONY: kagent-ui-port-forward
kagent-ui-port-forward: ## Open the UI in a browser and port-forward to localhost:8082
kagent-ui-port-forward: use-kind-cluster
	open http://localhost:8082/
	kubectl --context kind-$(KIND_CLUSTER_NAME) port-forward -n kagent service/kagent-ui 8082:8080

.PHONY: kagent-addon-install
kagent-addon-install: ## Install Istio, Grafana, Prometheus, and metrics-server addons on the kind cluster
kagent-addon-install: use-kind-cluster
	istioctl install --context kind-$(KIND_CLUSTER_NAME) --set profile=demo -y
	kubectl apply --context kind-$(KIND_CLUSTER_NAME) -f contrib/addons/grafana.yaml
	kubectl apply --context kind-$(KIND_CLUSTER_NAME) -f contrib/addons/prometheus.yaml
	kubectl apply --context kind-$(KIND_CLUSTER_NAME) -f contrib/addons/metrics-server.yaml
	# wait for pods to be ready
	kubectl wait --context kind-$(KIND_CLUSTER_NAME) --for=condition=Ready pod -l app.kubernetes.io/name=grafana    -n kagent --timeout=60s
	kubectl wait --context kind-$(KIND_CLUSTER_NAME) --for=condition=Ready pod -l app.kubernetes.io/name=prometheus -n kagent --timeout=60s

.PHONY: open-dev-container
open-dev-container: ## Build and start the devcontainer
	@echo "Building and starting dev container..."
	devcontainer up --workspace-folder .

.PHONY: otel-local
otel-local: ## Start a local Jaeger container for OpenTelemetry tracing (UI at localhost:16686)
	$(CONTAINER_RUNTIME) rm -f jaeger-desktop || true
	$(CONTAINER_RUNTIME) run -d --name jaeger-desktop --restart=always -p 16686:16686 -p 4317:4317 -p 4318:4318 jaegertracing/jaeger:2.7.0
	@echo "Jaeger UI available at http://localhost:16686/"

.PHONY: kind-debug
kind-debug: ## Install btop/htop inside the kind control-plane container and launch btop
	@echo "Debugging the kind cluster..."
	@echo "Enter the kind cluster control plane container..."
	$(CONTAINER_RUNTIME) exec -it $(KIND_CLUSTER_NAME)-control-plane bash -c 'apt-get update && apt-get install -y btop htop'
	$(CONTAINER_RUNTIME) exec -it $(KIND_CLUSTER_NAME)-control-plane bash -c 'btop --utf-force'


##@ Security

.PHONY: audit
audit: ## Run CVE audits for Go, UI, and Python dependencies
	echo "Running CVE audit GO"
	make -C go govulncheck
	echo "Running CVE audit UI"
	make -C ui audit
	echo "Running CVE audit PYTHON"
	make -C python audit

.PHONY: report/image-cve
report/image-cve: ## Scan built images with grype and write CVE CSV reports to reports/
report/image-cve: audit build
	echo "Running CVE scan :: CVE -> CSV ... reports/$(SEMVER)/"
	grype $(CONTAINER_RUNTIME):$(CONTROLLER_IMG) -o template -t reports/cve-report.tmpl --file reports/$(SEMVER)/controller-cve.csv
	grype $(CONTAINER_RUNTIME):$(KAGENT_ADK_IMG) -o template -t reports/cve-report.tmpl --file reports/$(SEMVER)/kagent-adk-cve.csv
	grype $(CONTAINER_RUNTIME):$(UI_IMG)         -o template -t reports/cve-report.tmpl --file reports/$(SEMVER)/ui-cve.csv


##@ Cleanup

.PHONY: clean
clean: ## Remove build artifacts, prune images, and delete the buildx builder
clean: prune-kind-cluster
clean: prune-images
ifneq ($(CONTAINER_RUNTIME),podman)
	$(CONTAINER_RUNTIME) buildx rm $(BUILDX_BUILDER_NAME)  -f || true
endif
	rm -rf ./go/core/bin

.PHONY: prune-kind-cluster
prune-kind-cluster: ## Remove dangling container images from the kind node
	echo "Pruning dangling container images from kind  ..."
	$(CONTAINER_RUNTIME) exec $(KIND_CLUSTER_NAME)-control-plane crictl images --no-trunc --quiet | \
	grep '<none>' | awk '{print $$3}' | xargs -r -n1 $(CONTAINER_RUNTIME) exec $(KIND_CLUSTER_NAME)-control-plane crictl rmi || :

.PHONY: prune-images
prune-images: ## Remove old kagent images and dangling images from the local daemon
	echo "Pruning dangling container images ..."
	$(CONTAINER_RUNTIME) images --format '{{.Repository}}:{{.Tag}} {{.ID}}' | \
	grep -v ":$(VERSION) " | grep kagent | grep -v '<none>' | awk '{print $$2}' | xargs -r $(CONTAINER_RUNTIME) rmi || :
	$(CONTAINER_RUNTIME) images --filter dangling=true -q | xargs -r $(CONTAINER_RUNTIME) rmi || :