Makefile

# Stratos Makefile — verb + modifier pattern
#
# Usage:
#   make build                  Build frontend + all backend platforms
#   make build frontend         Build frontend only
#   make build backend          Cross-compile all backend platforms
#   make build backend PLATFORM=linux/amd64  Build single backend platform
#   make test                   Run all tests
#   make test frontend          Frontend tests only
#   make test backend           Backend tests only
#   make test e2e               Run Playwright E2E tests
#   make release                Release all targets (cf + github)
#   make release cf             CF-pushable zip
#   make release github         GitHub release archives
#   make install                Install dependencies
#   make stage                  Stage for local testing
#   make clean                  Remove all build output
#   make clean frontend         Remove frontend build only
#   make clean backend          Remove backend binaries only
#   make clean dist             Remove everything (including node_modules)
#   make check                  Run all quality gates (lint + gate)
#   make check e2e              Run Playwright E2E tests
#   make stamp frontend         Generate build-info.ts with version metadata
#   make dump version           Print resolved version variables
#
# Variables:
#   FINAL=strip                 Strip prerelease from version (persisted)
#   DRYRUN=yes                  Preview actions without executing
#   VERSION=vX.Y.Z              Override version
#   PLATFORM=os/arch            Override target platform
#
# Debug: make _HIDE= <target>  — exposes all internal variables
#
# See docs/build-and-packaging.md for full documentation.

include version.mk

# ── Directories ───────────────────────────────────────────────
$(_HIDE)DIST_DIR    := dist
$(_HIDE)RELEASE_DIR := $($(_HIDE)DIST_DIR)/release
$(_HIDE)BIN_DIR     := $($(_HIDE)DIST_DIR)/bin

# ── Cross-cutting variables ───────────────────────────────────
# DRYRUN=yes   — preview actions without executing (any verb)
# FINAL=strip  — strip prerelease from version, persist to package.json
DRYRUN ?=
FINAL  ?=

# Literal comma — required because $(call) and $(subst) both use commas
# as argument separators, so a literal cannot appear inline.
$(_HIDE)COMMA := ,

# ── Platform detection ────────────────────────────────────────
# Override with: make build PLATFORM=linux/amd64
PLATFORM ?=
$(_HIDE)HOST_OS   := $(shell uname -s | tr '[:upper:]' '[:lower:]')
$(_HIDE)HOST_ARCH := $(patsubst x86_64,amd64,$(patsubst aarch64,arm64,$(shell uname -m)))

# Parse PLATFORM override or default to host
ifdef PLATFORM
  $(_HIDE)PLAT_WORDS := $(subst /, ,$(subst -, ,$(subst _, ,$(PLATFORM))))
  $(_HIDE)TARGET_OS   := $(word 1,$($(_HIDE)PLAT_WORDS))
  $(_HIDE)TARGET_ARCH := $(or $(word 2,$($(_HIDE)PLAT_WORDS)),$($(_HIDE)HOST_ARCH))
else
  $(_HIDE)TARGET_OS   := $($(_HIDE)HOST_OS)
  $(_HIDE)TARGET_ARCH := $($(_HIDE)HOST_ARCH)
endif

$(_HIDE)CURRENT_PLATFORM := $($(_HIDE)TARGET_OS)/$($(_HIDE)TARGET_ARCH)

# Cross-compilation: set GOOS/GOARCH when target differs from host
$(_HIDE)GO_ENV :=
ifneq ($($(_HIDE)TARGET_OS),$($(_HIDE)HOST_OS))
  $(_HIDE)GO_ENV += GOOS=$($(_HIDE)TARGET_OS)
endif
ifneq ($($(_HIDE)TARGET_ARCH),$($(_HIDE)HOST_ARCH))
  $(_HIDE)GO_ENV += GOARCH=$($(_HIDE)TARGET_ARCH)
endif

# ── Modifier flags ───────────────────────────────────────────
$(_HIDE)WANT_FRONTEND :=
$(_HIDE)WANT_BACKEND  :=
$(_HIDE)WANT_E2E      :=

ifneq ($(filter frontend,$(MAKECMDGOALS)),)
  $(_HIDE)WANT_FRONTEND := yes
endif
ifneq ($(filter backend,$(MAKECMDGOALS)),)
  $(_HIDE)WANT_BACKEND := yes
endif
ifneq ($(filter e2e,$(MAKECMDGOALS)),)
  $(_HIDE)WANT_E2E := yes
endif

# Default: frontend + backend when none specified (unless e2e),
# but only for verbs that use these modifiers (not clean/dump).
ifneq ($(filter build test dev stamp,$(MAKECMDGOALS)),)
ifeq ($($(_HIDE)WANT_FRONTEND)$($(_HIDE)WANT_BACKEND)$($(_HIDE)WANT_E2E),)
  $(_HIDE)WANT_FRONTEND := yes
  $(_HIDE)WANT_BACKEND  := yes
endif
endif

$(_HIDE)WANT_CF     :=
$(_HIDE)WANT_GITHUB :=

ifneq ($(filter cf,$(MAKECMDGOALS)),)
  $(_HIDE)WANT_CF := yes
endif
ifneq ($(filter github,$(MAKECMDGOALS)),)
  $(_HIDE)WANT_GITHUB := yes
endif
ifneq ($(filter release,$(MAKECMDGOALS)),)
ifeq ($($(_HIDE)WANT_CF)$($(_HIDE)WANT_GITHUB),)
  $(_HIDE)WANT_CF     := yes
  $(_HIDE)WANT_GITHUB := yes
endif
endif

$(_HIDE)WANT_VERSION :=
$(_HIDE)WANT_ACTIONS :=

ifneq ($(filter version,$(MAKECMDGOALS)),)
  $(_HIDE)WANT_VERSION := yes
endif
ifneq ($(filter actions,$(MAKECMDGOALS)),)
  $(_HIDE)WANT_ACTIONS := yes
endif
# Default: version + actions when none specified for dump
ifneq ($(filter dump,$(MAKECMDGOALS)),)
ifeq ($($(_HIDE)WANT_VERSION)$($(_HIDE)WANT_ACTIONS),)
  $(_HIDE)WANT_VERSION := yes
  $(_HIDE)WANT_ACTIONS := yes
endif
endif

# cf modifier defaults to linux/amd64 unless PLATFORM is set
ifeq ($($(_HIDE)WANT_CF),yes)
  ifndef PLATFORM
    PLATFORM := linux/amd64
    $(_HIDE)TARGET_OS   := linux
    $(_HIDE)TARGET_ARCH := amd64
    $(_HIDE)GO_ENV      := GOOS=linux GOARCH=amd64
    $(_HIDE)CURRENT_PLATFORM := linux/amd64
  endif
endif

$(_HIDE)WANT_CLEAN_DIST :=
$(_HIDE)WANT_LINT       :=
$(_HIDE)WANT_GATE       :=
$(_HIDE)WANT_TESTS      :=
$(_HIDE)WANT_COVERAGE   :=

ifneq ($(filter dist,$(MAKECMDGOALS)),)
  $(_HIDE)WANT_CLEAN_DIST := yes
endif
ifneq ($(filter lint,$(MAKECMDGOALS)),)
  $(_HIDE)WANT_LINT := yes
endif
ifneq ($(filter gate,$(MAKECMDGOALS)),)
  $(_HIDE)WANT_GATE := yes
endif
ifneq ($(filter tests,$(MAKECMDGOALS)),)
  $(_HIDE)WANT_TESTS := yes
endif
ifneq ($(filter coverage,$(MAKECMDGOALS)),)
  $(_HIDE)WANT_COVERAGE := yes
endif
# Default: all checks when none specified
ifneq ($(filter check,$(MAKECMDGOALS)),)
ifeq ($($(_HIDE)WANT_LINT)$($(_HIDE)WANT_GATE)$($(_HIDE)WANT_TESTS)$($(_HIDE)WANT_COVERAGE)$($(_HIDE)WANT_E2E),)
  $(_HIDE)WANT_LINT     := yes
  $(_HIDE)WANT_GATE     := yes
endif
endif

# No-op targets so modifiers don't error
# Note: lint has its own standalone recipe — not listed here.
.PHONY: frontend backend cf github dist version e2e actions gate tests coverage
frontend backend cf github dist version e2e actions gate tests coverage:
	@:

# No-op targets for bump modifiers (consumed by BUMP_MOD filter).
.PHONY: major minor patch rc alpha beta prerelease
major minor patch rc alpha beta prerelease:
	@:

# ── Load action registry ─────────────────────────────────────
# Variable path prevents tab-completion parsers from following
# the include (template syntax would confuse static parsers).
$(_HIDE)ACTIONS := actions
include $($(_HIDE)ACTIONS).mk

# ══════════════════════════════════════════════════════════════
# Object definitions — grouped by component, not by verb.
# Each section defines all actions for one component.
# ══════════════════════════════════════════════════════════════

# ── Frontend ──────────────────────────────────────────────────

define build.frontend
	@echo "Building frontend (production)..."
	bun run build
	@echo "Frontend built: $($(_HIDE)DIST_DIR)/frontend/browser/"
endef
$(call register, build, frontend, $(_HIDE)stamp.frontend)

define test.frontend
	@echo "Running frontend tests..."
	bun run test
endef
$(call register, test, frontend)

define clean.frontend
	rm -rf $($(_HIDE)DIST_DIR)/frontend .angular dist-devkit
endef
$(call register, clean, frontend)

define dev.frontend
	BACKEND_PORT=$(BACKEND_PORT) bun run ng serve --port $(FRONTEND_PORT) --proxy-config proxy.conf.cjs
endef
$(call register, dev, frontend)

# stamp.frontend recipe is defined in version.mk (shared library)
$(call register, stamp, frontend)

# ── Backend ───────────────────────────────────────────────────

define build.backend
	@if [ -n "$(PLATFORM)" ]; then \
		echo "Building backend for $($(_HIDE)CURRENT_PLATFORM)..."; \
		mkdir -p $($(_HIDE)BIN_DIR); \
		cd src/jetstream && $($(_HIDE)GO_ENV) go build -ldflags "$($(_HIDE)GO_LDFLAGS)" -o ../../$($(_HIDE)BIN_DIR)/jetstream; \
		echo "Backend built: $($(_HIDE)BIN_DIR)/jetstream"; \
	else \
		echo "Cross-compiling backend for all platforms..."; \
		chmod +x build/cross-compile.sh; \
		./build/cross-compile.sh "$($(_HIDE)SEMVER_VERSION)" "$($(_HIDE)BUILD_DATE)" "$($(_HIDE)BUILD_VCS_ID)"; \
		echo "All platform binaries built: $($(_HIDE)BIN_DIR)/"; \
	fi
endef
$(call register, build, backend)

define test.backend
	@echo "Running backend tests..."
	cd src/jetstream && go test ./... -v -count=1
endef
$(call register, test, backend)

define clean.backend
	rm -rf $($(_HIDE)DIST_DIR)/bin
	cd src/jetstream && rm -f jetstream jetstream.exe jetstream.darwin
endef
$(call register, clean, backend)

define dev.backend
	@NEED_BUILD=false; \
	if [ ! -f $($(_HIDE)BIN_DIR)/jetstream ]; then \
		NEED_BUILD=true; \
	elif ! file $($(_HIDE)BIN_DIR)/jetstream | grep -qi "$$(uname -s)"; then \
		echo "Backend binary is not for this platform, rebuilding..."; \
		NEED_BUILD=true; \
	fi; \
	if [ "$$NEED_BUILD" = true ]; then \
		echo "Building backend for host platform..."; \
		$(MAKE) build backend PLATFORM=$($(_HIDE)HOST_OS)/$($(_HIDE)HOST_ARCH); \
	fi
	cd src/jetstream && CONSOLE_PROXY_TLS_ADDRESS=:$(BACKEND_PORT) ../../$($(_HIDE)BIN_DIR)/jetstream
endef
$(call register, dev, backend)

# ── E2E variables (consumed by test.e2e and check.e2e) ──
# These are recipe-local, not cross-cutting. DRYRUN=yes is the
# existing cross-cutting variable (wired to bump); the e2e recipes
# also consume it, mapping to Playwright's --list.
E2E_BROWSERS    ?=
E2E_TRACE       ?=
E2E_VIDEO       ?=
E2E_SCREENSHOTS ?=

# Helpers — translate the variables above into Playwright CLI flags.

# Convert "a,b,c" → "--project=a --project=b --project=c"
# Empty → "--project=chromium" (default)
# "all" → ""                    (no filter; runs every project in playwright.config.ts)
_e2e_browsers = $(if $(1),$(if $(filter all,$(1)),,$(addprefix --project=,$(subst $($(_HIDE)COMMA), ,$(1)))),--project=chromium)

# Emit '--name value' iff value is non-empty
_e2e_flag = $(if $(2),--$(1) $(2),)

# Emit '--name' iff value == "yes"
_e2e_toggle = $(if $(filter yes,$(2)),--$(1),)

# ── E2E ───────────────────────────────────────────────────────

define test.e2e
	@echo "Running Playwright E2E tests..."
	@$(if $(E2E_VIDEO),E2E_VIDEO=$(E2E_VIDEO) )$(if $(E2E_SCREENSHOTS),E2E_SCREENSHOTS=$(E2E_SCREENSHOTS) )npx playwright test \
		$(call _e2e_browsers,$(E2E_BROWSERS)) \
		$(call _e2e_flag,trace,$(E2E_TRACE)) \
		$(call _e2e_toggle,list,$(DRYRUN))
endef
$(call register, test, e2e)

# ── Check (quality gates) ────────────────────────────────────
# make check          — lint + gate (default)
# make check lint     — ESLint + go vet only
# make check gate     — lint + unit tests (= bun run gate-check)
# make check tests    — unit tests only
# make check coverage — unit tests with coverage
# make check e2e      — Playwright E2E core tests

define check.lint
	@echo "Running lint checks..."
	bun run lint
	cd src/jetstream && go fmt ./... && go vet ./...
endef
$(call register, check, lint)

define check.gate
	@echo "Running gate checks (lint + unit tests)..."
	bun run gate-check
	cd src/jetstream && go test ./... -v -count=1
endef
$(call register, check, gate)

define check.tests
	@echo "Running unit tests..."
	bun run test
	cd src/jetstream && go test ./... -v -count=1
endef
$(call register, check, tests)

define check.coverage
	@echo "Running unit tests with coverage..."
	bun run test -- --coverage
endef
$(call register, check, coverage)

define check.e2e
	@echo "Running Playwright E2E core tests..."
	@$(if $(E2E_VIDEO),E2E_VIDEO=$(E2E_VIDEO) )$(if $(E2E_SCREENSHOTS),E2E_SCREENSHOTS=$(E2E_SCREENSHOTS) )npx playwright test e2e/tests/core/ \
		$(call _e2e_browsers,$(E2E_BROWSERS)) \
		$(call _e2e_flag,trace,$(E2E_TRACE)) \
		$(call _e2e_toggle,list,$(DRYRUN))
endef
$(call register, check, e2e)

# ── CF release ────────────────────────────────────────────────

define release.cf
	@chmod +x build/release-cf.sh
	@./build/release-cf.sh "$($(_HIDE)SEMVER_VERSION)"
endef
$(call register, release, cf)

# ── GitHub release ────────────────────────────────────────────

define release.github
	@chmod +x build/release-github.sh
	@./build/release-github.sh "$($(_HIDE)SEMVER_VERSION)"
endef
$(call register, release, github)

# ══════════════════════════════════════════════════════════════
# Verb wiring — declare each verb after all objects are registered.
# ══════════════════════════════════════════════════════════════

# ── FINAL=strip — finalize version, then re-exec without FINAL ──
# Strips prerelease from package.json and re-invokes Make so all
# version variables resolve fresh from the updated package.json.
# Uses MAKEOVERRIDES filter to prevent FINAL from propagating.
ifeq ($(FINAL),strip)
.PHONY: $(_HIDE)finalize-and-reexec
$(_HIDE)finalize-and-reexec:
	@echo "Finalizing version (stripping prerelease)..."
	@chmod +x build/version-bump.sh
	@./build/version-bump.sh bump release
	@echo "Re-running: $(MAKE) $(MAKECMDGOALS)"
	@$(MAKE) FINAL= $(MAKECMDGOALS)
$(filter-out frontend backend cf github dist version e2e actions lint gate tests coverage,$(MAKECMDGOALS)): $(_HIDE)finalize-and-reexec ; @:
else ifneq ($(FINAL),)
$(error Unknown FINAL value '$(FINAL)' — supported: strip)
endif

# ── Cross-cutting modifier allowances ────────────────────────
# These modifiers affect build behavior through variables (e.g.,
# cf forces PLATFORM=linux/amd64) rather than via a registered recipe.
$(call allow, build, cf)

$(call declare_verb, build)
$(call declare_verb, test)
$(call declare_verb, release)
$(call declare_verb, stamp)
$(call declare_verb, check)
# Skip dev verb declaration when 'dev' is used as a bump modifier
ifeq ($(filter bump,$(MAKECMDGOALS)),)
$(call declare_verb, dev)
else
.PHONY: dev
dev: ;@:
endif

# ── Stamp defaults ────────────────────────────────────────────
# stamp with no modifier stamps frontend
ifeq ($($(_HIDE)WANT_FRONTEND)$($(_HIDE)WANT_BACKEND),)
stamp: $(_HIDE)stamp.frontend
endif

# ── Clean (special behavior) ─────────────────────────────────
# make clean           — build output + release artifacts
# make clean frontend  — frontend build only
# make clean backend   — backend binaries only
# make clean dist      — above + node_modules

define clean.release
	rm -rf $($(_HIDE)DIST_DIR)/release $($(_HIDE)DIST_DIR)/cf-package $($(_HIDE)DIST_DIR)/install $($(_HIDE)DIST_DIR)/stratos-cf-*.zip
endef

define clean.dist
	rm -rf $($(_HIDE)DIST_DIR)/frontend .angular dist-devkit $($(_HIDE)DIST_DIR)/bin
	cd src/jetstream && rm -f jetstream jetstream.exe jetstream.darwin
	rm -rf node_modules src/frontend/packages/*/node_modules
endef

$(call register_always, clean, release)
$(call register, clean, dist, $(_HIDE)clean.release)

$(call declare_verb_default, clean, $(_HIDE)clean.release)

# ── Dump (introspection) ─────────────────────────────────────
# dump.version recipe is defined in version.mk (shared library)
$(call register, dump, version)

define dump.actions
	@echo "Registered verb+modifier pairs:"
	@for pair in $($(_HIDE)REGISTRY); do \
		verb=$${pair%%.*}; mod=$${pair#*.}; \
		printf "  make %-12s %s\n" "$$verb" "$$mod"; \
	done
endef
$(call register, dump, actions)

$(call declare_verb, dump)

# ── Development ports ─────────────────────────────────────────
BACKEND_PORT  ?= 5443
FRONTEND_PORT ?= 5440

# ── Simple verbs (no modifiers) ──────────────────────────────
.PHONY: stage install lint security gosec trivy vuln

stage:
	@chmod +x build/install-local.sh
	@./build/install-local.sh

install:
	@echo "Installing dependencies..."
	bun install
	@echo "Dependencies installed."

# lint: standalone verb, but no-op when used as check modifier
ifeq ($(filter check,$(MAKECMDGOALS)),)
lint:
	bun run lint
	cd src/jetstream && go fmt ./... && go vet ./...
else
lint: ;@:
endif

security: gosec trivy vuln

gosec:
	@which gosec > /dev/null || (echo "gosec not installed. Run: go install github.com/securego/gosec/v2/cmd/gosec@latest" && exit 1)
	cd src/jetstream && gosec -quiet ./... || true

trivy:
	@which trivy > /dev/null || (echo "trivy not installed. See https://github.com/aquasecurity/trivy" && exit 1)
	trivy fs --security-checks vuln,config src/jetstream || true

vuln:
	@which govulncheck > /dev/null || (echo "govulncheck not installed. Run: go install golang.org/x/vuln/cmd/govulncheck@latest" && exit 1)
	cd src/jetstream && govulncheck ./... || true

# ── Bump (version management) ─────────────────────────────────
# bump uses its own modifier set not shared with other verbs,
# so it is wired manually rather than via register/declare_verb.

$(_HIDE)BUMP_MOD := $(filter major minor patch dev alpha beta rc prerelease,$(MAKECMDGOALS))

.PHONY: bump
bump:
	@set -- $($(_HIDE)BUMP_MOD); \
	if [ $$# -eq 0 ]; then \
		echo "Usage: make bump <major|minor|patch|dev|alpha|beta|rc|prerelease>" >&2; \
		exit 1; \
	elif [ $$# -gt 1 ]; then \
		echo "Only one bump modifier allowed" >&2; \
		exit 1; \
	fi
	@chmod +x build/version-bump.sh
	@./build/version-bump.sh bump $($(_HIDE)BUMP_MOD) $(if $(filter yes,$(DRYRUN)),--dry-run)

# ── Help ──────────────────────────────────────────────────────
.PHONY: help
help:
	@echo "Stratos Build System ($($(_HIDE)SEMVER_VERSION) | $($(_HIDE)CURRENT_PLATFORM))"
	@echo ""
	@echo "Building:"
	@echo "  make build                Build frontend + all backend platforms"
	@echo "  make build frontend       Build frontend only"
	@echo "  make build backend        Cross-compile all backend platforms"
	@echo "  make build backend PLATFORM=linux/amd64  Build single platform"
	@echo ""
	@echo "Testing:"
	@echo "  make test                 Run all tests"
	@echo "  make test frontend        Frontend tests only"
	@echo "  make test backend         Backend tests only"
	@echo "  make test e2e             Run Playwright E2E tests"
	@echo "  make lint                 Run linters"
	@echo ""
	@echo "Quality:"
	@echo "  make check                Run all quality gates (lint + gate)"
	@echo "  make check lint           Lint checks only"
	@echo "  make check gate           Lint + unit tests (gate-check)"
	@echo "  make check tests          Unit tests only"
	@echo "  make check coverage       Unit tests with coverage"
	@echo "  make check e2e            Playwright E2E core tests"
	@echo ""
	@echo "Release:"
	@echo "  make release              Create CF zip + GitHub archives"
	@echo "  make release cf           CF-pushable zip only"
	@echo "  make release github       GitHub release archives only"
	@echo ""
	@echo "Setup:"
	@echo "  make install              Install dependencies (bun install)"
	@echo "  make stage                Stage production build for local testing"
	@echo ""
	@echo "Clean:"
	@echo "  make clean                Remove all build output"
	@echo "  make clean frontend       Remove frontend build only"
	@echo "  make clean backend        Remove backend binaries only"
	@echo "  make clean dist           Remove everything (including node_modules)"
	@echo ""
	@echo "Other:"
	@echo "  make stamp frontend       Generate build-info.ts with version metadata"
	@echo "  make security             Run security scans"
	@echo "  make dump version         Print version and build metadata"
	@echo ""
	@echo "Development:"
	@echo "  make dev frontend         Start frontend dev server (port $(FRONTEND_PORT))"
	@echo "  make dev backend          Start backend dev server (port $(BACKEND_PORT))"
	@echo "  Override ports:  make dev backend BACKEND_PORT=5543"
	@echo "                   make dev frontend FRONTEND_PORT=5540 BACKEND_PORT=5543"
	@echo ""
	@echo "Version:"
	@echo "  make bump major           Next major release (v5.0.0)"
	@echo "  make bump minor           Next minor release (v4.10.0)"
	@echo "  make bump patch           Next patch release (v4.9.4)"
	@echo "  make bump dev             Increment dev prerelease (dev.N)"
	@echo "  make bump alpha           Set/increment alpha prerelease (alpha.N)"
	@echo "  make bump beta            Set/increment beta prerelease (beta.N)"
	@echo "  make bump rc              Set/increment rc prerelease (rc.N)"
	@echo "  make bump prerelease      Set/increment prerelease (prerelease.N)"
	@echo ""
	@echo "Variables:"
	@echo "  FINAL=strip               Strip prerelease from version (persisted)"
	@echo "  DRYRUN=yes                Preview actions without executing"
	@echo "  VERSION=vX.Y.Z            Override version"
	@echo "  PLATFORM=os/arch          Override target platform"
	@echo ""
	@echo "  Examples:"
	@echo "    make release cf FINAL=strip       Finalize version + package"
	@echo "    make bump dev DRYRUN=yes          Preview version bump"
	@echo ""
	@echo "Registry:"
	@echo "  make dump actions         List all registered verb+modifier pairs"
	@if [ -f site.mk ]; then $(MAKE) --no-print-directory $(_HIDE)site-help 2>/dev/null || (echo "" && echo "Site-specific targets available (see site.mk)"); fi

# ── Deprecated target shims ──────────────────────────────────
include deprecated.mk

# ── Site-specific overrides ──────────────────────────────────
$(_HIDE)SITE := site
-include $($(_HIDE)SITE).mk