Makefile

# open-agent-kit Makefile
# Common development tasks for the project
#
# Prerequisites:
#   - Python 3.13 (3.14+ not yet supported due to dependency constraints)
#   - uv (https://docs.astral.sh/uv/getting-started/installation/)
#
# Quick start:
#   make setup    # Install dependencies
#   make check    # Run all checks
#
# CLI architecture:
#   oak-dev  → symlink to .venv/bin/oak (editable, from uv sync)
#   oak      → uv tool install oak-ci (stable from PyPI, separate venv)
#   Both can coexist simultaneously.

.PHONY: help setup setup-full sync lock uninstall cli-stable cli-dev cli-dual cli-verify test test-fast test-parallel test-cov lint format format-check typecheck check clean build ci-dev ci-start ci-stop ci-restart ui-shared-install ui-build ui-check ui-lint ui-dev ui-restart swarm-ui-build swarm-ui-check swarm-ui-lint swarm-ui-dev skill-build skill-check docs-dev docs-build docs-preview dogfood-reset acp-smoke

# Where uv/pipx put global binaries (respect XDG on Linux)
USER_BIN_DIR := $(or $(shell uv tool dir --bin 2>/dev/null),$(HOME)/.local/bin)

# Default target
help:
	@echo "open-agent-kit development commands"
	@echo ""
	@echo "Prerequisites: Python 3.13, uv (https://docs.astral.sh/uv)"
	@echo ""
	@echo "  Setup:"
	@echo "    make setup         Install dependencies and editable repo CLI (oak-dev)"
	@echo "    make sync          Re-sync dependencies after git pull"
	@echo "    make lock          Update lockfile after changing pyproject.toml"
	@echo "    make uninstall     Remove dev environment and local editable CLI install"
	@echo "    make cli-stable    Install/reinstall stable oak CLI from PyPI (oak)"
	@echo "    make cli-dev       Install/reinstall editable repo CLI (oak-dev)"
	@echo "    make cli-dual      Install both stable oak and editable oak-dev"
	@echo "    make cli-verify    Show where oak/oak-dev resolve and tool state"
	@echo ""
	@echo "  Testing:"
	@echo "    make test          Run all tests with coverage"
	@echo "    make test-fast     Run tests in parallel without coverage (fastest)"
	@echo "    make test-parallel Run tests in parallel with coverage"
	@echo "    make test-cov      Run tests and open coverage report"
	@echo ""
	@echo "  Code Quality:"
	@echo "    make lint          Run ruff linter"
	@echo "    make format        Format code with black and ruff --fix"
	@echo "    make format-check  Check formatting without changes (CI mode)"
	@echo "    make typecheck     Run mypy type checking"
	@echo "    make check         Run all CI checks (format-check, typecheck, test)"
	@echo ""
	@echo "  Build:"
	@echo "    make build         Build package"
	@echo "    make clean         Remove build artifacts and cache"
	@echo ""
	@echo "  Codebase Intelligence (CI daemon):"
	@echo "    make ci-dev        Run daemon with hot reload (development)"
	@echo "    make ci-start      Start the daemon"
	@echo "    make ci-stop       Stop the daemon"
	@echo "    make ci-restart    Stop and start the daemon (picks up code changes)"
	@echo ""
	@echo "  UI Development:"
	@echo "    make ui-build      Build UI static assets"
	@echo "    make ui-check      Verify UI assets are in sync (for CI)"
	@echo "    make ui-lint       Run ESLint on UI code"
	@echo "    make ui-dev        Run UI development server with hot reload"
	@echo "    make ui-restart    Build UI and restart daemon"
	@echo ""
	@echo "  Swarm UI Development:"
	@echo "    make swarm-ui-build   Build swarm UI static assets"
	@echo "    make swarm-ui-check   Verify swarm UI assets are in sync (for CI)"
	@echo "    make swarm-ui-lint    Run ESLint on swarm UI code"
	@echo "    make swarm-ui-dev     Run swarm UI development server with hot reload"
	@echo ""
	@echo "  Skills:"
	@echo "    make skill-build   Generate skill reference files from schema"
	@echo "    make skill-check   Verify skill files are in sync (for CI)"
	@echo ""
	@echo "  Documentation:"
	@echo "    make docs-dev      Run docs site with hot reload (development)"
	@echo "    make docs-build    Build docs site for production"
	@echo "    make docs-preview  Preview built docs site locally"
	@echo ""
	@echo "  ACP Integration:"
	@echo "    make acp-smoke     Run live ACP smoke tests against running daemon"
	@echo ""
	@echo "  Dogfooding:"
	@echo "    make dogfood-reset Reset oak environment (reinstall with all features)"

# Setup targets
setup:
	@command -v uv >/dev/null 2>&1 || { echo "Error: uv is not installed. Visit https://docs.astral.sh/uv/getting-started/installation/"; exit 1; }
	uv sync --extra dev
	@# oak-dev = symlink to .venv/bin/oak (editable install from uv sync)
	@mkdir -p "$(USER_BIN_DIR)"
	ln -sf "$(CURDIR)/.venv/bin/oak" "$(USER_BIN_DIR)/oak-dev"
	@echo "\nSetup complete! All dependencies installed."
	@echo "Run 'make check' to verify everything works."
	@echo ""
	@echo "Repo-local dev CLI: use 'oak-dev' in this repository."
	@echo "Global stable CLI remains 'oak' for other repositories."
	@echo ""
	@echo "CI feature dev workflow:"
	@echo "  make ci-dev      Run daemon with hot reload (auto-restarts on code changes)"
	@echo "  make ci-restart  Manual restart after code changes"
	@echo "  make ui-restart  Build UI and restart daemon (for UI changes)"
	@if ! echo "$$PATH" | tr ':' '\n' | grep -qx "$(USER_BIN_DIR)"; then \
		echo ""; \
		echo "WARNING: $(USER_BIN_DIR) is not in your PATH."; \
		echo "Add this to your ~/.zshrc (or ~/.bashrc):"; \
		echo "  export PATH=\"$(USER_BIN_DIR):\$$PATH\""; \
		echo "Then run: source ~/.zshrc"; \
	fi

# Alias for backwards compatibility
setup-full: setup

sync:
	uv sync --extra dev
	@# Refresh oak-dev symlink (in case .venv was recreated)
	@mkdir -p "$(USER_BIN_DIR)"
	ln -sf "$(CURDIR)/.venv/bin/oak" "$(USER_BIN_DIR)/oak-dev"
	@echo "Dependencies synced and oak-dev symlink refreshed."
	@if ! echo "$$PATH" | tr ':' '\n' | grep -qx "$(USER_BIN_DIR)"; then \
		echo ""; \
		echo "WARNING: $(USER_BIN_DIR) is not in your PATH."; \
		echo "Add this to your ~/.zshrc (or ~/.bashrc):"; \
		echo "  export PATH=\"$(USER_BIN_DIR):\$$PATH\""; \
		echo "Then run: source ~/.zshrc"; \
	fi

lock:
	uv lock
	@echo "Lockfile updated. Run 'make sync' to install."

uninstall:
	rm -f "$(USER_BIN_DIR)/oak-dev"
	uv tool uninstall oak-ci 2>/dev/null || true
	rm -rf .venv
	@echo "Dev environment and CLI installs removed."
	@echo "To reinstall: make setup"

cli-stable:
	uv tool install oak-ci --python python3.13 --force
	@echo "Stable CLI installed as 'oak'."

cli-dev: sync
	@echo "Editable CLI installed as 'oak-dev'."

cli-dual: cli-stable cli-dev
	@echo "Dual install complete: oak (stable from PyPI), oak-dev (editable from .venv)."

cli-verify:
	@echo "Command resolution:"
	@which -a oak oak-dev 2>/dev/null || true
	@echo ""
	@echo "oak-dev target:"
	@readlink "$(USER_BIN_DIR)/oak-dev" 2>/dev/null || echo "  (not installed)"
	@echo ""
	@echo "uv tools:"
	@uv tool list 2>/dev/null || true

# Testing targets
test:
	uv run pytest tests/ -v

test-fast:
	uv run pytest tests/ -v --no-cov -n auto

test-parallel:
	uv run pytest tests/ -v -n auto

test-cov:
	uv run pytest tests/ -v
	@echo "\nOpening coverage report..."
	@open htmlcov/index.html 2>/dev/null || xdg-open htmlcov/index.html 2>/dev/null || echo "Open htmlcov/index.html in your browser"

# Code quality targets
lint:
	uv run ruff check src/ tests/

format:
	uv run black src/ tests/
	uv run ruff check --fix src/ tests/

format-check:
	uv run black src/ tests/ --check --diff
	uv run ruff check src/ tests/

typecheck:
	uv run mypy src/open_agent_kit

# Combined check (mirrors CI pr-check.yml)
check: format-check typecheck test-parallel
	@echo "\nAll checks passed!"

# Build targets
build:
	uv build

clean:
	rm -rf build/
	rm -rf dist/
	rm -rf *.egg-info/
	rm -rf src/*.egg-info/
	rm -rf .pytest_cache/
	rm -rf .mypy_cache/
	rm -rf .ruff_cache/
	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

# Codebase Intelligence daemon targets
#
# Dev workflow for CI feature:
#   1. make ci-dev     - Run with hot reload (best for development)
#   2. make ci-restart - Manual restart after code changes
#
# Note: 'make ci-dev' uses uvicorn --reload which auto-restarts on file changes
# in src/. This is the recommended way to develop the CI feature.

ci-dev:
	@echo "Starting CI daemon with hot reload (Ctrl+C to stop)..."
	@echo "The daemon will auto-restart when you modify files in src/"
	@echo ""
	OAK_CI_PROJECT_ROOT=$(PWD) uv run uvicorn open_agent_kit.features.team.daemon.server:create_app --factory --host 127.0.0.1 --port 37800 --reload --reload-dir src/

ci-start:
	uv run oak ci start

ci-stop:
	uv run oak ci stop

ci-restart: ci-stop
	@sleep 1
	@echo "Starting CI daemon..."
	uv run oak ci start

# Shared UI dependencies (installed once, used by both team + swarm UIs)
ui-shared-install:
	cd src/open_agent_kit/ui/shared && npm install

# UI Development targets
ui-build: ui-shared-install
	cd src/open_agent_kit/features/team/daemon/ui && npm install && npm run build

ui-check:
	$(MAKE) ui-build
	@if [ -n "$$(git status --porcelain src/open_agent_kit/features/team/daemon/static)" ]; then \
		echo "Error: UI assets are out of sync. Please run 'make ui-build' and commit the changes."; \
		exit 1; \
	fi

ui-lint:
	cd src/open_agent_kit/features/team/daemon/ui && npm run lint

ui-dev:
	cd src/open_agent_kit/features/team/daemon/ui && npm run dev

# Combo target: build UI and restart daemon (for UI development workflow)
ui-restart: ui-build ci-restart
	@echo "UI rebuilt and daemon restarted."

# Swarm UI Development targets
swarm-ui-build: ui-shared-install
	cd src/open_agent_kit/features/swarm/daemon/ui && npm install && npm run build

swarm-ui-check:
	$(MAKE) swarm-ui-build
	@if [ -n "$$(git status --porcelain src/open_agent_kit/features/swarm/daemon/static)" ]; then \
		echo "Error: Swarm UI assets are out of sync. Please run 'make swarm-ui-build' and commit the changes."; \
		exit 1; \
	fi

swarm-ui-lint:
	cd src/open_agent_kit/features/swarm/daemon/ui && npm run lint

swarm-ui-dev:
	cd src/open_agent_kit/features/swarm/daemon/ui && npm run dev

# Skill asset generation targets
#
# Some skills include generated reference files (e.g., database schema docs).
# Generators are auto-discovered: features/*/skills/*/generate_*.py
# Pattern mirrors ui-build/ui-check for frontend assets.

skill-build:
	uv run python scripts/build_skill_assets.py

skill-check:
	uv run python scripts/build_skill_assets.py --check

# Documentation site targets
docs-dev:
	cd docs && npm install && npm run dev

docs-build:
	cd docs && npm ci && npm run build

docs-preview:
	cd docs && npm install && npm run preview

# Dogfooding target - reset oak environment (preserves oak/ user content)
dogfood-reset:
	@echo "Resetting oak dogfooding environment..."
	-uv run oak ci stop 2>/dev/null || true
	-uv run oak remove --force 2>/dev/null || true
	uv sync --all-extras
	uv run oak init --agent claude --no-interactive
	@echo ""
	@echo "Dogfooding environment reset. Run 'make ci-dev' to start daemon with hot reload."

# ACP smoke test - live integration test against running daemon
acp-smoke:  ## Run live ACP smoke tests against running daemon
	uv run python scripts/acp_smoke_test.py

ui-check-all: 
	make ui-check && make swarm-ui-check

ui-lint-all:
	make ui-lint && make swarm-ui-lint

ui-build-all:
	make ui-build && make swarm-ui-build