Makefile

# Build System
# ============
# This Makefile orchestrates the mux build process.
#
# Quick Start:
#   make help          - Show all available targets
#   make dev           - Start development server with hot reload
#   make build         - Build all targets (parallel when possible)
#   make static-check  - Run fast local static checks (oxlint + typecheck + fmt-check)
#   make static-check-full - Run the full CI static check suite (adds type-aware ESLint on all files)
#   make test          - Run tests
#
# Parallelism:
#   Runs in parallel by default for faster builds. Use -j1 for sequential execution.
#   Individual targets can opt out with .NOTPARALLEL if needed.
#
# Backwards Compatibility:
#   All commands also work via `bun run` (e.g., `bun run dev` calls `make dev`)
#
# Adding New Targets:
#   Add `## Description` after the target to make it appear in `make help`
#
# Build Reproducibility:
#   AVOID CONDITIONAL BRANCHES (if/else) IN BUILD TARGETS AT ALL COSTS.
#   Branches reduce reproducibility - builds should fail fast with clear errors
#   if dependencies are missing, not silently fall back to different behavior.
#
# Telemetry in Development:
#   Telemetry is enabled by default in dev mode (same as production).
#   It is automatically disabled in CI, test environments, and automation contexts.
#   To manually disable telemetry, set XUM_DISABLE_TELEMETRY=1.

# Developer env: XUM_* is canonical. MUX_* and unprefixed VITE_*/BACKEND_* remain accepted.
# React profiling in development:
# Default desktop dev launches opt into Xum's lightweight component render sampler so
# already-running dev instances can be inspected without a restart. Override with
# `make start XUM_PROFILE_REACT=0` when measuring an uninstrumented baseline.
XUM_PROFILE_REACT ?= $(or $(MUX_PROFILE_REACT),1)
XUM_VITE_HOST ?= $(or $(MUX_VITE_HOST),$(VITE_HOST),127.0.0.1)
XUM_VITE_PORT ?= $(or $(MUX_VITE_PORT),$(VITE_PORT),5173)
XUM_VITE_ALLOWED_HOSTS ?= $(or $(MUX_VITE_ALLOWED_HOSTS),$(VITE_ALLOWED_HOSTS))
XUM_BACKEND_HOST ?= $(or $(MUX_BACKEND_HOST),$(BACKEND_HOST),127.0.0.1)
XUM_BACKEND_PORT ?= $(or $(MUX_BACKEND_PORT),$(BACKEND_PORT),3000)

# `make dev-server` starts the backend with auth on: any local account can reach a loopback port,
# and an open backend runs commands as you. Make generates one random token per run, so nodemon
# restarts keep it, and exports it to the recipe's processes. It stays in the environment (argv is
# visible to every local account) and in <XUM_ROOT>/server.lock (mode 0600). The browser sends it
# through the Vite proxy as `/?token=<token>` once; the proxy adds nothing, so the Vite port is no
# way around auth. XUM_DEV_SERVER_AUTH_TOKEN picks the token. The ambient XUM_SERVER_AUTH_TOKEN is
# never reused: agent shells export the real server's token. XUM_DEV_SERVER_NO_AUTH=1 restores the
# open backend, for hosts where you are the only account. Keep XUM_ROOT outside the checkout: Vite
# serves the checkout to anyone who can reach its port, and public/ without any file checks.
ifeq ($(XUM_DEV_SERVER_NO_AUTH),1)
override DEV_SERVER_AUTH_FLAG := --no-auth
else
override DEV_SERVER_AUTH_FLAG :=
# Only when dev-server is a goal: `:=` runs node at parse time, and every make invocation parses this.
ifneq ($(filter dev-server,$(MAKECMDGOALS)),)
# `override` beats `make -e`; `$(value ...)` keeps a chosen token's dollar signs from being expanded.
override export XUM_SERVER_AUTH_TOKEN := $(or $(value XUM_DEV_SERVER_AUTH_TOKEN),$(shell node -p "require('crypto').randomBytes(32).toString('hex')"))
ifeq ($(XUM_SERVER_AUTH_TOKEN),)
$(error could not generate the dev-server auth token: is node on PATH?)
endif
endif
endif

# While nodemon restarts the backend, its TCP port is free for any local account to bind, and the
# browser's reconnect URL carries the token. So Vite reaches the backend over a Unix socket in a
# private folder (`xum server --unix-socket` makes it 0700 and refuses a folder that is not yours):
# no other account can create the socket's name. The TCP port stays for the CLI and scripts, which
# read the lockfile. The path is short on purpose (sun_path holds about 100 bytes) and has the
# backend host and port in its name (a TCP address can be bound once, so no two running backends
# share it), so parallel dev servers do not collide. XUM_BACKEND_SOCKET picks another.
# The recipe reads the path from the environment (`"$XUM_BACKEND_SOCKET"`), never from the command
# text: it crosses three shells, and a path with spaces or quotes must stay one argument.
# Windows has no such folder and keeps TCP for the Vite hop.
ifneq ($(OS),Windows_NT)
ifneq ($(filter dev-server,$(MAKECMDGOALS)),)
ifndef XUM_BACKEND_SOCKET
# scripts/devServerSocketPath.ts: another account can create the default folder first, and the
# backend refuses a folder that is not ours, so a folder that is not safely ours is replaced by a
# fresh private one next to it (and says so). It creates the folder (0700) when it is missing, so
# that no other account takes the name while make builds, and a dry run does the same.
shq = '$(subst ','\'',$(1))'
XUM_BACKEND_SOCKET := $(shell bun scripts/devServerSocketPath.ts $(call shq,$(or $(XDG_RUNTIME_DIR),/tmp)/xum-dev-$(shell id -u)) $(call shq,b$(XUM_BACKEND_PORT)-$(subst /,_,$(subst :,_,$(XUM_BACKEND_HOST))).sock))
ifeq ($(XUM_BACKEND_SOCKET),)
$(error no private folder for the dev-server socket (the reason is above, or bun is not on PATH): set XUM_BACKEND_SOCKET to a socket path in a folder that only you can write to, or XDG_RUNTIME_DIR to such a folder)
endif
endif
export XUM_BACKEND_SOCKET
endif
else
# The Windows recipe starts the backend on TCP only: an ambient path must not reach the Vite proxy.
override XUM_BACKEND_SOCKET :=
endif

# Use PATH-resolved bash for portability across different systems.
# - Windows: /usr/bin/bash doesn't exist in Chocolatey's make environment or GitHub Actions
# - NixOS: /bin/bash doesn't exist, bash is in /nix/store/...
# - Other systems: /usr/bin/env bash resolves from PATH
ifeq ($(OS),Windows_NT)
SHELL := bash
else
SHELL := /usr/bin/env bash
endif
.SHELLFLAGS := -eu -o pipefail -c

# Enable parallel execution by default (only if user didn't specify -j)
ifeq (,$(filter -j%,$(MAKEFLAGS)))
MAKEFLAGS += -j
endif

# Issue #3831: macOS may SIGKILL the copied esbuild inode while the platform binary still execs.
# ESBUILD_BINARY_PATH is not used because only esbuild's JS API honors it, not the Go CLI.
# Prefer the host platform package: ensure-mac-sharp-runtime-deps adds darwin packages on any
# host, and a bare wildcard would sort @esbuild/darwin-arm64 first (issue #3338).
ESBUILD_HOST_PLATFORM := $(subst Linux,linux,$(subst Darwin,darwin,$(shell uname -s)))-$(subst x86_64,x64,$(subst aarch64,arm64,$(shell uname -m)))
ESBUILD_BIN = $(firstword $(wildcard node_modules/@esbuild/$(ESBUILD_HOST_PLATFORM)/bin/esbuild) $(wildcard node_modules/@esbuild/*/bin/esbuild) node_modules/esbuild/bin/esbuild)

# Common esbuild flags for CLI API bundle (ESM format for trpc-cli)
ESBUILD_CLI_FLAGS := --bundle --format=esm --platform=node --target=node20 --outfile=dist/cli/api.mjs --external:zod --external:commander --external:jsonc-parser --external:@trpc/server --external:ssh2 --external:cpu-features --external:typescript --banner:js="import{createRequire}from\"module\";globalThis.require=createRequire(import.meta.url);"

# Common esbuild flags for server runtime Docker bundle.
# Place runtime bundles under dist/runtime so frontend dist/*.js layers remain stable.
# External native modules (node-pty, ssh2) and electron remain runtime dependencies.
# A CJS bundle leaves import.meta empty, and @anthropic-ai/sandbox-runtime calls
# fileURLToPath(import.meta.url) when it loads, which crashed the server at startup. So
# import.meta.url is the bundle's own file URL. The banner repeats "use strict" because a
# directive only counts before the first statement.
ESBUILD_SERVER_FLAGS := --bundle --platform=node --target=node22 --format=cjs --outfile=dist/runtime/server-bundle.js --external:@lydell/node-pty --external:electron --external:ssh2 --alias:jsonc-parser=jsonc-parser/lib/esm/main.js --minify --define:import.meta.url=__xumBundleUrl --banner:js='"use strict";var __xumBundleUrl=require("url").pathToFileURL(__filename).href;'

# Common esbuild flags for tokenizer worker bundle used by server-bundle runtime.
# Each encoding ships as its own bundle next to the worker, and the worker bundle requires it
# lazily. Inlining all four made every per-encoding worker parse ~14 MB (~11.7 s CPU) before it
# loaded its one encoding (#4816). Keep this list in sync with ENCODING_LOADERS in tokenizer.worker.ts.
TOKENIZER_ENCODINGS := claude o200k_base cl100k_base p50k_base
TOKENIZER_ENCODING_BUNDLES := $(foreach e,$(TOKENIZER_ENCODINGS),dist/runtime/tokenizer-encoding-$(e).js)
ESBUILD_TOKENIZER_WORKER_FLAGS := --bundle --platform=node --target=node22 --format=cjs --outfile=dist/runtime/tokenizer.worker.js --minify $(foreach e,$(TOKENIZER_ENCODINGS),--alias:ai-tokenizer/encoding/$(e)=./tokenizer-encoding-$(e).js) --external:./tokenizer-encoding-*
ESBUILD_MCP_ICON_WORKER_FLAGS := --bundle --platform=node --target=node22 --format=cjs --outfile=dist/runtime/mcpIconDecode.js --external:sharp --minify
# The analytics worker loads DuckDB's native bindings, which esbuild cannot bundle; the
# Docker runtime stage copies node_modules/@duckdb next to the other externalized modules.
ESBUILD_ANALYTICS_WORKER_FLAGS := --bundle --platform=node --target=node22 --format=cjs --outfile=dist/runtime/analyticsWorker.js --external:@duckdb/* --external:electron --minify

# Include formatting rules
include fmt.mk

.PHONY: all build dev start clean help
.PHONY: build-renderer version build-icons build-static build-docker-runtime verify-docker-runtime-artifacts
.PHONY: lint lint-eslint lint-full lint-fix check-oxlint-config check-no-css-zoom typecheck static-check static-check-full
.PHONY: crap crap-check test-crap-scripts tree-sitter-grammars dry-check test-dry-scripts mutate-check test-mutate-scripts
.PHONY: formal-check
.PHONY: test-bugbash-repros test-bugbash-known-failures bugbash-sandbox-key bugbash-sandbox-image bugbash-sandbox-publish bug-bash-sandbox-recover bug-bash-sandbox-check test-bugbash-repros-sandbox
.PHONY: test test-unit test-unit-ci test-host-proof test-integration test-watch test-coverage test-e2e test-e2e-perf perf-tape-replay smoke-test
.PHONY: dist dist-mac dist-win dist-linux install-mac-arm64 ensure-mac-sharp-runtime-deps check-appimage-icons check-mac-attach-file-runtime
.PHONY: vscode-ext vscode-ext-install
.PHONY: docs-server check-docs-links
.PHONY: storybook storybook-run storybook-build storybook-flake-check test-storybook test-storybook-webkit test-storybook-paint-fixtures storybook-budget
.PHONY: benchmark-terminal bench bench-compare test-loop-baseline first-load-js page-timing first-run-view-parity bug-bash mcp-apps-e2e test-stories generate-phone-chrome check-phone-chrome
.PHONY: ensure-deps mux
.PHONY: check-startup-imports check-startup-imports-runtime check-react-compiler check-test-routing check-test-seam-comments test-bench-scripts

# Use the package binary instead of its internal path so native-preview can change wrappers safely.
TSGO := bun run tsgo

# Node.js version check
REQUIRED_NODE_VERSION := 20
NODE_VERSION := $(shell node --version | sed 's/v\([0-9]*\).*/\1/')

define check_node_version
	@if [ "$(NODE_VERSION)" -lt "$(REQUIRED_NODE_VERSION)" ]; then \
		echo "Error: Node.js v$(REQUIRED_NODE_VERSION) or higher is required"; \
		echo "Current version: v$(NODE_VERSION)"; \
		echo ""; \
		echo "To upgrade Node.js:"; \
		echo "  1. Install 'n' version manager: curl -L https://raw.githubusercontent.com/tj/n/master/bin/n | sudo bash -s -- lts"; \
		echo "  2. Or use 'n' if already installed: sudo n $(REQUIRED_NODE_VERSION)"; \
		echo ""; \
		exit 1; \
	fi
endef

# Detect if browser opener is available that Storybook can use
# Storybook uses 'open' package which tries xdg-open on Linux, open on macOS, start on Windows
HAS_BROWSER_OPENER := $(shell command -v xdg-open >/dev/null 2>&1 && echo "yes" || echo "no")
STORYBOOK_OPEN_FLAG := $(if $(filter yes,$(HAS_BROWSER_OPENER)),,--no-open)

DOCS_SOURCES := $(shell find docs -type f \( -name '*.mdx' -o -name '*.md' -o -name 'docs.json' \))
BUILTIN_SKILL_SOURCES := $(shell find src/node/builtinSkills -type f | sort)

TS_SOURCES := $(shell find src -type f \( -name '*.ts' -o -name '*.tsx' \))

# Default target
all: build

# Sentinel file to track when dependencies are installed
# Depends on package.json and bun.lock - rebuilds if either changes
node_modules/.installed: package.json bun.lock
	@echo "Dependencies out of date or missing, running bun install --frozen-lockfile..."
	@# Keep local validation from silently rewriting bun.lock when a different Bun version is installed.
	@bun install --frozen-lockfile
	@touch node_modules/.installed

# Legacy target for backwards compatibility
ensure-deps: node_modules/.installed

# Run compiled CLI with trailing arguments (builds only if missing)
mux: ## Run the compiled mux CLI (e.g., make mux server --port 3000)
	@test -f dist/cli/index.js -a -f dist/cli/api.mjs || $(MAKE) build-main
	@node dist/cli/index.js $(filter-out $@,$(MAKECMDGOALS))

# Catch unknown targets passed to mux (prevents "No rule to make target" errors)
ifneq ($(filter mux,$(MAKECMDGOALS)),)
%:
	@:
endif

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

## Development
ifeq ($(OS),Windows_NT)
dev: node_modules/.installed build-main ## Start development server (Vite + nodemon watcher for Windows compatibility)
	@echo "Starting dev mode (3 watchers: nodemon for main process, esbuild for api, vite for renderer)..."
	# On Windows, use npm run because bunx doesn't correctly pass arguments to concurrently
	# https://github.com/oven-sh/bun/issues/18275
	@NODE_OPTIONS="--max-old-space-size=4096" \
		npm x concurrently -k --raw \
		"bun x nodemon --watch src --watch tsconfig.main.json --watch tsconfig.json --ext ts,tsx,json,js --ignore dist --ignore node_modules --exec node scripts/build-main-watch.js" \
		'npx esbuild src/cli/api.ts $(ESBUILD_CLI_FLAGS) --watch' \
		"vite"
else
dev: node_modules/.installed build-main build-preload ## Start development server (Vite + tsgo watcher for 10x faster type checking)
	@bun x concurrently -k \
		"bun x nodemon --watch src/node/workflowRuntime --ext js --exec 'bun scripts/gen_workflow_runtime_sources.ts'" \
		"bun x concurrently \"$(TSGO) -w -p tsconfig.main.json\" \"bun x tsc-alias -w -p tsconfig.main.json\"" \
		'$(ESBUILD_BIN) src/cli/api.ts $(ESBUILD_CLI_FLAGS) --watch' \
		"vite"
endif

ifeq ($(OS),Windows_NT)
dev-server: node_modules/.installed build-main ## Start server mode with hot reload. Use XUM_VITE_HOST=0.0.0.0 XUM_VITE_ALLOWED_HOSTS=<public-host> for remote access
	@echo "Starting dev-server..."
	@echo "  Backend (IPC/WebSocket): http://$(XUM_BACKEND_HOST):$(XUM_BACKEND_PORT)"
	@echo "  Frontend (with HMR):     http://$(XUM_VITE_HOST):$(XUM_VITE_PORT)"
	@echo "  Auth:                    $(if $(DEV_SERVER_AUTH_FLAG),DISABLED (XUM_DEV_SERVER_NO_AUTH=1). Any local account can control this backend.,token required (not printed). It is in server.lock under XUM_ROOT. Open the frontend with /?token=<token>.)"
	@echo ""
	@echo "For remote access: make dev-server XUM_VITE_HOST=0.0.0.0 XUM_VITE_ALLOWED_HOSTS=<public-host>"
	@# On Windows, use npm run because bunx doesn't correctly pass arguments
	@npm x concurrently -k \
		"nodemon --watch src --watch tsconfig.main.json --watch tsconfig.json --ext ts,tsx,json,js --ignore dist --ignore node_modules scripts/build-main-watch.js" \
		'npx esbuild src/cli/api.ts $(ESBUILD_CLI_FLAGS) --watch' \
		"set NODE_ENV=development&& nodemon --watch dist/cli/index.js --watch dist/cli/server.js --delay 500ms dist/cli/index.js server $(DEV_SERVER_AUTH_FLAG) --host $(XUM_BACKEND_HOST) --port $(XUM_BACKEND_PORT)" \
		"set XUM_VITE_HOST=$(XUM_VITE_HOST)&& set XUM_VITE_PORT=$(XUM_VITE_PORT)&& set XUM_VITE_ALLOWED_HOSTS=$(XUM_VITE_ALLOWED_HOSTS)&& set XUM_BACKEND_HOST=$(XUM_BACKEND_HOST)&& set XUM_BACKEND_PORT=$(XUM_BACKEND_PORT)&& vite"
else
dev-server: node_modules/.installed build-main ## Start server mode with hot reload. Use XUM_VITE_HOST=0.0.0.0 XUM_VITE_ALLOWED_HOSTS=<public-host> for remote access
	@echo "Starting dev-server..."
	@echo "  Backend (IPC/WebSocket): http://$(XUM_BACKEND_HOST):$(XUM_BACKEND_PORT)"
	@echo "  Frontend (with HMR):     http://$(XUM_VITE_HOST):$(XUM_VITE_PORT)"
	@echo "  Auth:                    $(if $(DEV_SERVER_AUTH_FLAG),DISABLED (XUM_DEV_SERVER_NO_AUTH=1). Any local account can control this backend.,token required (not printed). It is in server.lock under XUM_ROOT. Open the frontend with /?token=<token>.)"
	@echo "  Vite -> backend:         Unix socket $$XUM_BACKEND_SOCKET"
	@echo ""
	@echo "For remote access: make dev-server XUM_VITE_HOST=0.0.0.0 XUM_VITE_ALLOWED_HOSTS=<public-host>"
	@# Keep tsgo -> tsc-alias sequential to avoid transient unresolved @/ imports in dist during restarts.
	@bun x concurrently -k \
		"bun x nodemon --watch src --watch tsconfig.main.json --watch tsconfig.json --ext ts,tsx,json,js --ignore dist --ignore node_modules --exec 'node scripts/build-main-watch.js'" \
		'$(ESBUILD_BIN) src/cli/api.ts $(ESBUILD_CLI_FLAGS) --watch' \
		"bun x nodemon --watch dist/.main-build-complete --delay 300ms --exec 'NODE_ENV=development node dist/cli/index.js server $(DEV_SERVER_AUTH_FLAG) --unix-socket \"\$$XUM_BACKEND_SOCKET\" --host $(XUM_BACKEND_HOST) --port $(XUM_BACKEND_PORT)'" \
		"XUM_VITE_HOST=$(XUM_VITE_HOST) XUM_VITE_PORT=$(XUM_VITE_PORT) XUM_VITE_ALLOWED_HOSTS=$(XUM_VITE_ALLOWED_HOSTS) XUM_BACKEND_HOST=$(XUM_BACKEND_HOST) XUM_BACKEND_PORT=$(XUM_BACKEND_PORT) vite"
endif




dev-desktop-sandbox: ## Start an isolated Electron dev instance (fresh XUM_ROOT + free ports)
	@bun scripts/dev-desktop-sandbox.ts $(DEV_DESKTOP_SANDBOX_ARGS)
dev-server-sandbox: ## Start an isolated dev-server instance (fresh XUM_ROOT + free ports)
	@bun scripts/dev-server-sandbox.ts $(DEV_SERVER_SANDBOX_ARGS)

# bug-bash runs each e2e explore charter in its own bug-bash sandbox container (tests/bugbash/run.ts,
# #5714): a model picks its actions, so it never runs on the host. The explorers reach their models
# through a provider proxy per job, so the host needs BUGBASH_BUDGET_USD (one list-price cap for
# the run) and ANTHROPIC_API_KEY plus ANTHROPIC_BASE_URL. The app AI is BUGBASH_AI (default auto:
# run.ts probes BUGBASH_APP_MODEL through the run's budget, and falls back to the mock when the
# upstream is unavailable). The containers mount dist/. The checks (env, Docker, the image) run
# before the build, so a missing one refuses in about a second once the image is cached, not
# after the build. The first run pulls the image (about 1.4 GB), which takes minutes.
# Do not name a build goal (build-main, build-renderer, build-static) on the same make command line
# as bug-bash or mcp-apps-e2e: under -j the top-level make and the inner $(MAKE) build it twice at once.
bug-bash: ## Agent bug bash in the bug-bash sandbox: e2e explore charters x models (needs BUGBASH_BUDGET_USD)
	@bun tests/bugbash/run.ts --preflight $(BUGBASH_ARGS)
	@$(MAKE) --no-print-directory build-main build-renderer build-static
	@bun tests/bugbash/run.ts $(BUGBASH_ARGS)

# The bug-bash sandbox image (tests/bugbash/sandbox/build.sh, #5714). Each prints one value on
# stdout. Publishing runs only in the "Bug-bash sandbox image" workflow on main.
bugbash-sandbox-key: ## Print the inputs key of the bug-bash sandbox image for this checkout
	@./tests/bugbash/sandbox/build.sh --key

bugbash-sandbox-image: ## Build the bug-bash sandbox image locally (linux/amd64) and print its image ID
	@./tests/bugbash/sandbox/build.sh

bugbash-sandbox-publish: ## Workflow only: build and push the bug-bash sandbox image, print its publish record
	@./tests/bugbash/sandbox/build.sh --push

# The sandbox self-check (tests/bugbash/sandbox/selfCheckRun.ts, #5714): three jobs through the real
# launcher against a fake upstream, so it costs nothing and needs no key. CI runs it (bugbash-sandbox).
bug-bash-sandbox-check: build-main build-renderer build-static ## Check the bug-bash sandbox's isolation, proxy and export on this host ($$0, fake upstream)
	@cd tests/bugbash && bun sandbox/selfCheckRun.ts

# The repros of fixed bugs through the sandbox launcher, all on the mock app AI (the launcher gives
# exact-step runs no model). CI's bugbash-sandbox job runs this. The second phase selects the
# `tools-on` repros: BUGBASH_SCENARIO=scripted-tools runs the app with agent tools on against a
# loopback script (tests/bugbash/scriptedModel.ts), and startApp.ts refuses it outside this job.
# Its own tag filter comes after BUGBASH_REPRO_ARGS: e2e keeps the last --tag-mode, so `all`
# makes an extra --tag narrow the phase, and every test it selects carries `tools-on`. Like
# test-bugbash-repros, a BUGBASH_REPRO_ARGS filter can select tests of one phase only, so each
# phase passes --pass-with-no-tests and the last step fails when neither selected a test.
test-bugbash-repros-sandbox: build-main build-renderer build-static ## Bug-bash repros of fixed bugs in the bug-bash sandbox, mock app AI (no key, no model)
	@cd tests/bugbash && out=.e2e/repros-sandbox-$$(date -u +%Y%m%dT%H%M%SZ)-$$$$ && \
	  BUGBASH_AI=mock BUGBASH_AI_RESOLVED=mock BUGBASH_AI_REASON="sandbox repros" bun sandbox/launch.ts -- run --config e2e.config.ts --exclude-tag known-failure --exclude-tag agent --exclude-tag tools-on --pass-with-no-tests --output $$out $(BUGBASH_REPRO_ARGS) && \
	  BUGBASH_SCENARIO=scripted-tools BUGBASH_AI=mock BUGBASH_AI_RESOLVED=mock BUGBASH_AI_REASON="scripted-tools repros" bun sandbox/launch.ts -- run --config e2e.config.ts --exclude-tag known-failure --exclude-tag agent --pass-with-no-tests --output $$out-tools-on $(BUGBASH_REPRO_ARGS) --tag tools-on --tag-mode all && \
	  bun reproSelection.ts $$out/report.json $$out-tools-on/report.json

# Every sandbox launch lists the job containers that crashed launches of this checkout left
# (#5882). This removes the ones whose launcher is gone, by ID, and lists the rest.
bug-bash-sandbox-recover: ## Remove bug-bash sandbox containers of this checkout whose launcher is gone
	@cd tests/bugbash && bun sandbox/launch.ts --recover

# Bug-bash repro tests (tests/bugbash/repros/*.e2e.ts): exact UI steps, no model calls, against a
# seeded `xum server` (tests/bugbash/startApp.ts). Repros tagged `agent` use agent.* steps, so
# every run here passes --exclude-tag agent: only a model-driven sandbox job can run them. e2e needs Node.js 22.22.3+ or 24.8+ (E2E_NODE)
# and its own Chromium: `node_modules/.bin/e2e-web install chromium`.
E2E_NODE ?= node
BUGBASH_REPRO_RUN = cd tests/bugbash && E2E_TELEMETRY_DISABLED=1 PATH="$$(dirname "$$(command -v $(E2E_NODE))"):$$PATH" $(E2E_NODE) ../../node_modules/.bin/e2e run --config e2e.config.ts

test-bugbash-repros: build-main build-renderer build-static ## Bug-bash repro tests of fixed bugs (tag known-failure excluded; BUGBASH_REPRO_ARGS)
	@# A BUGBASH_REPRO_ARGS filter can select tests of one phase only, so each phase may select nothing
	@# (--pass-with-no-tests). The last step fails when the whole run selected no test. Old reports go first,
	@# so that step never counts a previous run.
	@rm -rf tests/bugbash/.e2e/repros-mock tests/bugbash/.e2e/repros
	@# [mock:...] prompts and terminals only work against the mock AI, so repros tagged mock-only pin it. Export
	@# it: a `VAR=x cd ... && e2e` prefix would set it for `cd` only.
	@export BUGBASH_AI_RESOLVED=mock BUGBASH_AI_REASON="mock-only repros"; $(BUGBASH_REPRO_RUN) --tag mock-only --exclude-tag known-failure --exclude-tag agent --exclude-tag tools-on --pass-with-no-tests --output .e2e/repros-mock $(BUGBASH_REPRO_ARGS)
	@# The other repros run on the app AI that BUGBASH_AI picks (default auto: real with a working key).
	@ai="$$(bun tests/bugbash/aiMode.ts)" || exit 2; eval "$$ai"; $(BUGBASH_REPRO_RUN) --exclude-tag mock-only --exclude-tag known-failure --exclude-tag agent --exclude-tag tools-on --pass-with-no-tests --output .e2e/repros $(BUGBASH_REPRO_ARGS)
	@bun tests/bugbash/reproSelection.ts tests/bugbash/.e2e/repros-mock/report.json tests/bugbash/.e2e/repros/report.json

test-bugbash-known-failures: build-main build-renderer build-static ## Bug-bash repros of open bugs: each fails until its issue is fixed
	@export BUGBASH_AI_RESOLVED=mock BUGBASH_AI_REASON="known-failure repros"; $(BUGBASH_REPRO_RUN) --tag known-failure --exclude-tag agent --output .e2e/repros-known $(BUGBASH_REPRO_ARGS)

# The MCP Apps suite runs only in the bug-bash sandbox (tests/bugbash/sandbox/launch.ts, #5714).
# agent.act steps reach BUGBASH_MODEL through a provider proxy for the job, so the host needs
# BUGBASH_BUDGET_USD (a list-price cap) and ANTHROPIC_API_KEY plus ANTHROPIC_BASE_URL. Its seed
# writes the MCP chat directly, so the app AI stays the mock. The container mounts dist/. As in
# bug-bash, the checks run before the build, and no build goal may share its make command line.
MCP_APPS_LAUNCH = cd tests/bugbash && BUGBASH_AI=mock BUGBASH_AI_RESOLVED=mock BUGBASH_AI_REASON="MCP Apps suite" bun sandbox/launch.ts
mcp-apps-e2e: ## MCP Apps e2e suite in the bug-bash sandbox (needs BUGBASH_BUDGET_USD)
	@$(MCP_APPS_LAUNCH) --preflight -- run --config e2e.mcpapps.config.ts --output .e2e/mcp-apps-preflight $(MCP_APPS_E2E_ARGS)
	@$(MAKE) --no-print-directory build-main build-renderer build-static
	@# The app AI is pinned to the mock, also over an exported BUGBASH_AI_RESOLVED. The shell PID
	@# keeps two runs that start in the same second apart (their output and proxy record).
	@$(MCP_APPS_LAUNCH) -- run --config e2e.mcpapps.config.ts --output .e2e/mcp-apps-$$(date -u +%Y%m%dT%H%M%SZ)-$$$$ $(MCP_APPS_E2E_ARGS)

# The story suite (tests/stories, agent.* steps), the Electron stories (tests/stories/electron)
# and the agent-tagged repros run only in the bug-bash sandbox (tests/bugbash/sandbox/launch.ts,
# #5714), each as its own job with its own 30-minute deadline and budget. Their agents
# reach BUGBASH_MODEL (default Sonnet 5.5) through a provider proxy for the job, so the host needs
# BUGBASH_BUDGET_USD (a list-price cap per job) and ANTHROPIC_API_KEY plus ANTHROPIC_BASE_URL. The
# app AI stays the mock. No agent repro exists yet, so that job may select none. As in
# mcp-apps-e2e, the checks run before the build, and no build goal may share its make command line.
STORIES_ENV = BUGBASH_AI=mock BUGBASH_AI_RESOLVED=mock BUGBASH_AI_REASON="story tests"
STORIES_LAUNCH = cd tests/stories && $(STORIES_ENV) bun ../bugbash/sandbox/launch.ts
AGENT_REPROS_LAUNCH = cd tests/bugbash && $(STORIES_ENV) bun sandbox/launch.ts
STORIES_RUN = run --config e2e.config.ts --exclude-tag known-failure
AGENT_REPROS_RUN = run --config e2e.config.ts --tag agent --exclude-tag known-failure --pass-with-no-tests
STORIES_ELECTRON_RUN = run --config e2e.electron.config.ts --exclude-tag known-failure
# The Electron binary of node_modules/electron: its postinstall downloads it, and a bun install
# that skipped it leaves none. The Electron stories mount node_modules read-only, so the host
# fetches it (launch.ts refuses an Electron job without it). A no-op once it is there.
.PHONY: electron-binary
electron-binary: ## Download the Electron binary into node_modules/electron (the Electron stories need it)
	@node node_modules/electron/install.js
test-stories: electron-binary ## Story tests, Electron stories and agent-tagged repros in the bug-bash sandbox (needs BUGBASH_BUDGET_USD)
	@$(STORIES_LAUNCH) --preflight -- $(STORIES_RUN) --output .e2e/stories-preflight $(STORIES_ARGS)
	@$(STORIES_LAUNCH) --preflight -- $(STORIES_ELECTRON_RUN) --output .e2e/stories-electron-preflight $(STORIES_ARGS)
	@$(AGENT_REPROS_LAUNCH) --preflight -- $(AGENT_REPROS_RUN) --output .e2e/agent-repros-preflight $(STORIES_ARGS)
	@# build-preload: Xum Electron's windows load dist/preload.js.
	@$(MAKE) --no-print-directory build-main build-preload build-renderer build-static
	@# The shell PID keeps two runs that start in the same second apart (their output and proxy record).
	@$(STORIES_LAUNCH) -- $(STORIES_RUN) --output .e2e/stories-$$(date -u +%Y%m%dT%H%M%SZ)-$$$$ $(STORIES_ARGS)
	@$(AGENT_REPROS_LAUNCH) -- $(AGENT_REPROS_RUN) --output .e2e/agent-repros-$$(date -u +%Y%m%dT%H%M%SZ)-$$$$ $(STORIES_ARGS)
	@# Last: make stops at the first failed job, so a failed Electron job skips no other job.
	@$(STORIES_LAUNCH) -- $(STORIES_ELECTRON_RUN) --output .e2e/stories-electron-$$(date -u +%Y%m%dT%H%M%SZ)-$$$$ $(STORIES_ARGS)

rlm-eval: ## Run the RLM lever eval against a running dev-server sandbox (see scripts/rlm-eval/run.ts header)
	@bun run scripts/rlm-eval/run.ts $(RLM_EVAL_ARGS)

start: node_modules/.installed build-main build-preload build-static ## Build and start Electron app
	@NODE_ENV=development XUM_PROFILE_REACT=$(XUM_PROFILE_REACT) bunx electron --remote-debugging-port=9222 .

# #6867: the shipped worker must carry a build id, or every release shares one cache again.
SERVICE_WORKER_STAMP_CHECK = grep -Eq '^const BUILD_ID = "[0-9a-f]{12}";$$' dist/service-worker.js || \
	{ echo "dist/service-worker.js has no build id (scripts/stamp-service-worker.ts did not run)"; exit 1; }

## Build targets (can run in parallel)
build: node_modules/.installed src/version.ts build-renderer build-main build-preload build-icons build-static ## Build all targets
	@$(SERVICE_WORKER_STAMP_CHECK)

.PHONY: update-models
update-models: node_modules/.installed ## Fetch latest LiteLLM model data, validate it, update models.json if changed
	@bun scripts/update_models.ts

# #3727: `make build UPDATE_MODELS=1` refreshes the vendored models.json before
# building; plain `make build` stays network-free and reproducible. The refresh
# must be a prerequisite of every catalog-consuming bundle (not just `build`) so
# parallel make cannot bundle the old catalog, and the phony prerequisite forces
# those bundles stale because models.json is not part of $(TS_SOURCES).
ifeq ($(UPDATE_MODELS),1)
build: update-models
build-renderer dist/cli/index.js dist/cli/api.mjs: update-models
endif

build-main: node_modules/.installed dist/cli/index.js dist/cli/api.mjs dist/workers/staticRowTree.worker.js ## Build main process

BUILTIN_AGENTS_GENERATED := src/node/services/agentDefinitions/builtInAgentContent.generated.ts
BUILTIN_SKILLS_GENERATED := src/node/services/agentSkills/builtInSkillContent.generated.ts
WORKFLOW_RUNTIME_SOURCES_GENERATED := src/node/services/workflows/workflowRuntimeSources.generated.ts
WORKFLOW_RUNTIME_SOURCES := $(shell find src/node/workflowRuntime -type f -name '*.js' 2>/dev/null)

$(BUILTIN_AGENTS_GENERATED): src/node/builtinAgents/*.md scripts/generate-builtin-agents.sh
	@./scripts/generate-builtin-agents.sh

$(BUILTIN_SKILLS_GENERATED): $(BUILTIN_SKILL_SOURCES) $(DOCS_SOURCES) scripts/generate-builtin-skills.sh scripts/gen_builtin_skills.ts
	@./scripts/generate-builtin-skills.sh

$(WORKFLOW_RUNTIME_SOURCES_GENERATED): $(WORKFLOW_RUNTIME_SOURCES) scripts/gen_workflow_runtime_sources.ts
	@bun scripts/gen_workflow_runtime_sources.ts

# models.json is bundled but not in $(TS_SOURCES); without this prerequisite a
# catalog-only refresh would leave a stale main bundle (#3727).
dist/cli/index.js: src/cli/index.ts src/desktop/main.ts src/cli/server.ts src/version.ts tsconfig.main.json tsconfig.json $(TS_SOURCES) src/common/utils/tokens/models.json $(BUILTIN_AGENTS_GENERATED) $(BUILTIN_SKILLS_GENERATED) $(BUILTIN_WORKFLOWS_GENERATED) $(WORKFLOW_RUNTIME_SOURCES_GENERATED)
	@echo "Building main process..."
	@NODE_ENV=production $(TSGO) -p tsconfig.main.json
	@NODE_ENV=production bun x tsc-alias -p tsconfig.main.json
	@# Signal nodemon only after alias rewriting is complete so it never boots from partial dist output.
	@mkdir -p dist
	@touch dist/.main-build-complete

# Build API CLI as ESM bundle (trpc-cli requires ESM with top-level await)
# node_modules/.installed is required here: unlike `bun x`, $(ESBUILD_BIN) cannot
# self-bootstrap, and parallel make would otherwise race this recipe against bun install.
dist/cli/api.mjs: src/cli/api.ts src/cli/proxifyOrpc.ts $(TS_SOURCES) node_modules/.installed
	@echo "Building API CLI (ESM)..."
	@$(ESBUILD_BIN) src/cli/api.ts $(ESBUILD_CLI_FLAGS)

# Node worker of `xum server` for the static workspace view (see scripts/build-row-tree-worker.ts).
dist/workers/staticRowTree.worker.js: scripts/build-row-tree-worker.ts $(TS_SOURCES) node_modules/.installed
	@echo "Building static view row-tree worker..."
	@bun scripts/build-row-tree-worker.ts $@

build-preload: node_modules/.installed dist/preload.js ## Build preload script

dist/preload.js: src/desktop/preload.ts $(TS_SOURCES)
	@echo "Building preload script..."
	@NODE_ENV=production bun build src/desktop/preload.ts \
		--format=cjs \
		--target=node \
		--external=electron \
		--sourcemap=inline \
		--outfile=dist/preload.js

build-renderer: node_modules/.installed src/version.ts ## Build renderer process
	@echo "Building renderer..."
	@bun x vite build
	@bun scripts/precompress-static.ts dist
	@# #6867: one service worker cache per build (needs the built index.html and the .br files).
	@bun scripts/stamp-service-worker.ts dist

build-static: ## Copy static assets to dist
	@echo "Copying static assets..."
	@mkdir -p dist
	@cp static/splash.html dist/splash.html
	@# Not public/service-worker.js: build-renderer's Vite copy is stamped with the build (#6867).
	@find public -mindepth 1 -maxdepth 1 ! -name service-worker.js -exec cp -r {} dist/ \;
	@# Copy TypeScript lib files for PTC runtime type validation (es5 through es2023).
	@# electron-builder ignores .d.ts files by default and this cannot be overridden:
	@# https://github.com/electron-userland/electron-builder/issues/5064
	@# Workaround: rename to .d.ts.txt extension to bypass the filter.
	@mkdir -p dist/typescript-lib
	@for f in node_modules/typescript/lib/lib.es5.d.ts \
	          node_modules/typescript/lib/lib.es2015*.d.ts \
	          node_modules/typescript/lib/lib.es2016*.d.ts \
	          node_modules/typescript/lib/lib.es2017*.d.ts \
	          node_modules/typescript/lib/lib.es2018*.d.ts \
	          node_modules/typescript/lib/lib.es2019*.d.ts \
	          node_modules/typescript/lib/lib.es2020*.d.ts \
	          node_modules/typescript/lib/lib.es2021*.d.ts \
	          node_modules/typescript/lib/lib.es2022*.d.ts \
	          node_modules/typescript/lib/lib.es2023*.d.ts; do \
		cp "$$f" "dist/typescript-lib/$$(basename $$f).txt"; \
	done

build-docker-runtime: build-main build-renderer build-static dist/runtime/server-bundle.js dist/runtime/tokenizer.worker.js dist/runtime/mcpIconDecode.js dist/runtime/analyticsWorker.js dist/static/.copied ## Build Docker runtime artifacts

verify-docker-runtime-artifacts: build-docker-runtime ## Verify required Docker runtime artifacts exist
	@$(SERVICE_WORKER_STAMP_CHECK)
	@test -f dist/runtime/server-bundle.js
	@test -f dist/runtime/tokenizer.worker.js
	@for e in $(TOKENIZER_ENCODINGS); do \
		test -f dist/runtime/tokenizer-encoding-$$e.js && \
		grep -qF "./tokenizer-encoding-$$e.js" dist/runtime/tokenizer.worker.js || exit 1; \
	done
	@test -f dist/runtime/mcpIconDecode.js
	@test -f dist/runtime/analyticsWorker.js
	@test -f dist/workers/staticRowTree.worker.js
	@test -f dist/static/splash.html
	@test -f dist/typescript-lib/lib.es2023.d.ts.txt

# Bundle server runtime for Docker image to reduce runtime dependencies/image size.
# Depend on build-main explicitly because dist/cli/server.js is emitted as a side effect.
dist/runtime/server-bundle.js: build-main $(TS_SOURCES)
	@echo "Bundling server runtime for Docker..."
	@test -f dist/cli/server.js
	@mkdir -p dist/runtime
	@$(ESBUILD_BIN) dist/cli/server.js $(ESBUILD_SERVER_FLAGS)

# Bundle tokenizer worker next to server-bundle.js so workerPool resolves it at runtime.
# Depend on build-main explicitly because tokenizer worker JS is emitted under dist/node/ as a side effect.
dist/runtime/tokenizer.worker.js: build-main $(TOKENIZER_ENCODING_BUNDLES)
	@echo "Bundling tokenizer worker for Docker..."
	@test -f dist/node/utils/main/tokenizer.worker.js
	@mkdir -p dist/runtime
	@$(ESBUILD_BIN) dist/node/utils/main/tokenizer.worker.js $(ESBUILD_TOKENIZER_WORKER_FLAGS)

dist/runtime/tokenizer-encoding-%.js: node_modules/.installed
	@mkdir -p dist/runtime
	@$(ESBUILD_BIN) ai-tokenizer/encoding/$* --bundle --platform=node --target=node22 --format=cjs --outfile=$@ --minify

# The disposable icon decoder must remain a separate process in bundled runtimes.
dist/runtime/mcpIconDecode.js: build-main
	@echo "Bundling MCP icon decoder for Docker..."
	@test -f dist/node/workers/mcpIconDecode.js
	@mkdir -p dist/runtime
	@$(ESBUILD_BIN) dist/node/workers/mcpIconDecode.js $(ESBUILD_MCP_ICON_WORKER_FLAGS)

# AnalyticsService starts analyticsWorker.js from the directory of the running server
# bundle, so the server image must ship it next to server-bundle.js (#5603).
dist/runtime/analyticsWorker.js: build-main
	@echo "Bundling analytics worker for Docker..."
	@test -f dist/node/services/analytics/analyticsWorker.js
	@mkdir -p dist/runtime
	@$(ESBUILD_BIN) dist/node/services/analytics/analyticsWorker.js $(ESBUILD_ANALYTICS_WORKER_FLAGS)

.PHONY: test-mcp-icon-electron
test-mcp-icon-electron: dist/runtime/mcpIconDecode.js ## Verify emitted and bundled icon workers with Electron's executable
	@# Electron 42+ downloads its binary on first require and logs that to stdout; keep only the path.
	@MCP_ICON_TEST_EXEC_PATH="$$(bun -p 'require("electron")' | tail -n 1)" MCP_ICON_TEST_WORKER_PATH="$(CURDIR)/dist/node/workers/mcpIconDecode.js" bun test src/node/services/mcpIconDecodeClient.test.ts
	@MCP_ICON_TEST_EXEC_PATH="$$(bun -p 'require("electron")' | tail -n 1)" MCP_ICON_TEST_WORKER_PATH="$(CURDIR)/dist/runtime/mcpIconDecode.js" bun test src/node/services/mcpIconDecodeClient.test.ts

# Docker runtime keeps static assets under dist/static/ for compatibility with existing image layout.
dist/static/.copied: static/splash.html
	@mkdir -p dist/static
	@cp -r static/* dist/static/
	@touch dist/static/.copied

# Always regenerate version file (marked as .PHONY above)
version: ## Generate version file
	@./scripts/generate-version.sh

src/version.ts: version

build/icons/512x512.png: docs/img/logo-white.svg scripts/generate-icons.ts
	@echo "Generating Linux icon set..."
	@bun scripts/generate-icons.ts linux-icons

# Platform-specific icon targets
ifeq ($(shell uname), Darwin)
build-icons: build/icon.icns build/icon.png build/icons/512x512.png ## Generate Electron app icons from logo (macOS builds both)

build/icon.icns: docs/img/logo-white.svg scripts/generate-icons.ts
	@echo "Generating macOS ICNS icon..."
	@bun scripts/generate-icons.ts icns
else
build-icons: build/icon.png build/icons/512x512.png ## Generate Electron app icons from logo (Linux builds PNG only)
endif

build/icon.png: docs/img/logo-white.svg scripts/generate-icons.ts
	@echo "Generating PNG icon..."
	@bun scripts/generate-icons.ts png

## Quality checks (can run in parallel)
# Keep the default local path fast. Docs link crawling and lockfile-free bench-agent
# verification stay in static-check-full so local validation remains responsive.
# static-check lints with oxlint, which runs the eslint.config.mjs rules it supports in seconds
# (.oxlintrc.json, kept in step by check-oxlint-config); static-check-full also runs type-aware
# ESLint on all files, so CI still catches what oxlint cannot check, including type-aware
# findings that a change surfaces in files it did not touch.
STATIC_CHECKS := typecheck fmt-check check-startup-imports check-react-compiler check-code-docs-links check-test-routing check-test-seam-comments check-oxlint-config check-no-css-zoom lint-shellcheck lint-hadolint

static-check: lint $(STATIC_CHECKS) ## Run fast local static checks

static-check-full: lint-full $(STATIC_CHECKS) check-bench-agent test-bench-scripts test-crap-scripts test-dry-scripts test-mutate-scripts check-docs-links ## Run the full CI static check suite

# The Python tools (pytest, Harbor, Crapper, ...) come from pyproject.toml's dependency groups.
# `uv run --locked --only-group <group>` installs a group exactly as uv.lock pins it, and fails
# when uv.lock is out of date. uv fetches a managed Python 3.12 if the system has none.
test-bench-scripts: ## Test the Terminal-Bench result checker and agent adapter with offline fixtures
	@uv run --locked --only-group test python -m pytest -q scripts/check_tbench_results_test.py
	@uv run --locked --only-group test --only-group harbor python -m pytest -q benchmarks/terminal_bench/mux_agent_test.py

# CRAP scores (scripts/crap/), with Crapper and the grammars from the crap group.
CRAP_REPORT := uv run --locked --quiet --only-group crap python scripts/crap/crapper_report.py

crap: ## Score every production src/ function with Crapper into .metrics/crap.json [COVERAGE="<lcov>..."]
	@mkdir -p .metrics
	@# Replace the last snapshot only after the report succeeds.
	@$(CRAP_REPORT) --top 20 $(foreach lcov,$(COVERAGE),--lcov $(lcov)) > .metrics/crap.json.tmp
	@mv .metrics/crap.json.tmp .metrics/crap.json
	@echo "Wrote .metrics/crap.json"

# The script exits 0 pass, 1 violations, 2 tool error; make reports any failure
# as 2, so hooks and CI call the script directly.
crap-check: ## CRAP gate on files changed since BASE (default: merge-base with origin/main) [COVERAGE="<lcov>..."] [CRAP_CHECK_ARGS=--json]
	@bun scripts/crap/check.ts --base "$(or $(BASE),$$(git merge-base origin/main HEAD))" \
		$(foreach lcov,$(COVERAGE),--coverage $(lcov)) $(CRAP_CHECK_ARGS)

CRAP_PYTHON := PYTHONDONTWRITEBYTECODE=1 uv run --locked --quiet --only-group crap --only-group test python

# tree-sitter-language-pack downloads its grammars from GitHub releases on first use. The
# script tests are in static-check-full (Required), so a transient failure there (seen: HTTP
# 504) must not fail the job before any test uses the grammars. The script checks the pack's
# manifest and bundle against sha256 pins that it holds, and then calls the pack's download(),
# which extracts the grammars from them (and fetches them when they are missing). CI sets
# GRAMMAR_STAGE_DIR to the directory that it caches, which holds only those two files, so a
# cache hit needs no network (pr.yml's "Restore tree-sitter grammars" step). A cold cache gets
# a budget of 15 minutes: the 504 outage of 2026-11-08 outlasted the old 3 tries 10 s apart.
# The default keeps an offline local run short. The script exits 64 on an HTTP 4xx that no
# retry changes, and on files that do not match the pins. A language added to `LANGUAGES` in
# the script needs no new key: the key hashes the script.
GRAMMAR_DOWNLOAD_BUDGET_SECS ?= 60
tree-sitter-grammars:
	@./scripts/retry.sh --budget-secs $(GRAMMAR_DOWNLOAD_BUDGET_SECS) --max-backoff-secs 60 --fatal-status 64 0 2 env $(CRAP_PYTHON) scripts/ci/download_tree_sitter_grammars.py

test-crap-scripts: tree-sitter-grammars ## Test the Crapper adapter (hand-counted fixtures) and crap-check end to end (needs uv)
	@$(CRAP_PYTHON) -m pytest -q -p no:cacheprovider scripts/crap/crapper_report_test.py
	@bun test ./scripts/crap/check.test.ts ./scripts/crap/agentGate.test.ts

# DRY gate (scripts/dry/): near-duplicate functions that the changes since
# BASE make (CI's mode: DRY_MODE; see .xum/skills/gauntlet). The script exits
# 0 no findings, 1 findings that no marker accepts, 2 tool error; CI calls
# it through scripts/dry/ci.ts.
dry-check: ## DRY gate on functions changed since BASE (default: merge-base with origin/main) [DRY_CHECK_ARGS=--json]
	@bun scripts/dry/check.ts --base "$(or $(BASE),$$(git merge-base origin/main HEAD))" $(DRY_CHECK_ARGS)

DRY_PYTHON := PYTHONDONTWRITEBYTECODE=1 uv run --locked --quiet --only-group dry --only-group test python

test-dry-scripts: tree-sitter-grammars ## Test the dryer adapter and dry-check end to end (needs uv)
	@$(DRY_PYTHON) -m pytest -q -p no:cacheprovider scripts/dry/dryer_report_test.py
	@bun test ./scripts/dry/check.test.ts

# Mutation gate (scripts/mutate/): mutants in the functions changed since BASE
# that the unit tests do not kill (CI's mode: MUTATION_MODE; see
# .xum/skills/gauntlet). The script exits 0 no survivors, 1 survivors that no
# marker accepts, 2 tool error, 3 a test failed
# without a mutant; CI calls it through scripts/mutate/ci.ts.
mutate-check: ## Mutation gate on functions changed since BASE (default: merge-base with origin/main) [COVERAGE="<lcov>..."] [MUTATE_CHECK_ARGS=--json]
	@bun scripts/mutate/check.ts --base "$(or $(BASE),$$(git merge-base origin/main HEAD))" \
		$(foreach lcov,$(COVERAGE),--coverage $(lcov)) $(MUTATE_CHECK_ARGS)

MUTATE_PYTHON := PYTHONDONTWRITEBYTECODE=1 uv run --locked --quiet --only-group mutate --only-group test python

test-mutate-scripts: tree-sitter-grammars ## Test the mutation runner and mutate-check end to end (needs uv)
	@$(MUTATE_PYTHON) -m pytest -q -p no:cacheprovider scripts/mutate/mutate_report_test.py
	@bun test ./scripts/mutate/check.test.ts

formal-check: ## Model-check that a Stop ends the auto-retry loop (TLA+/TLC, Java 11+; see .xum/skills/formal-stop-retry)
	@./.xum/skills/formal-stop-retry/check.sh

check-test-routing: node_modules/.installed ## Fail when a *.test.ts(x) file is run by no CI lane (or by two)
	@./scripts/check-test-routing.sh

check-oxlint-config: node_modules/.installed ## Fail when .oxlintrc.json applies different rules than eslint.config.mjs to any lint file
	@node scripts/check-oxlint-config.mjs

# CSS zoom lays out differently in Safari than in Chromium: iPhone Safari painted a Mermaid
# diagram far outside its frame. TS and TSX are covered by local/no-css-zoom.
check-no-css-zoom: node_modules/.installed ## Fail when a tracked CSS, HTML or SVG file declares the zoom property
	@bun test ./scripts/check-no-css-zoom.test.ts
	@bun scripts/check-no-css-zoom.ts

# <1 s: the matcher's tests run first so a broken guard cannot pass vacuously.
check-test-seam-comments: node_modules/.installed ## Fail when production code gains an unlisted "Exported for tests"-style comment
	@bun test ./scripts/check-test-seam-comments.test.ts
	@bun scripts/check-test-seam-comments.ts

check-bench-agent: node_modules/.installed src/version.ts $(BUILTIN_SKILLS_GENERATED) $(BUILTIN_WORKFLOWS_GENERATED) $(WORKFLOW_RUNTIME_SOURCES_GENERATED) ## Verify terminal-bench agent configuration and imports
	@./scripts/check-bench-agent.sh

LINT_PREREQS := node_modules/.installed src/version.ts $(BUILTIN_SKILLS_GENERATED) $(BUILTIN_WORKFLOWS_GENERATED) $(WORKFLOW_RUNTIME_SOURCES_GENERATED)
# Type-aware ESLint lints vscode/src, whose types (@types/vscode) come from the extension's own
# install. Without it, `make -j static-check-full` races typecheck's install and every vscode
# type reads as `error`.
ESLINT_PREREQS := $(LINT_PREREQS) vscode/node_modules/.installed

lint: $(LINT_PREREQS) ## Run oxlint on all files (the eslint.config.mjs rules it supports; no type-aware rules)
	@./scripts/lint.sh

lint-eslint: $(ESLINT_PREREQS) ## Run oxlint, then type-aware ESLint on files changed since the merge base with origin/main [XUM_LINT_BASE=<ref>]
	@./scripts/lint.sh --eslint

lint-full: $(ESLINT_PREREQS) ## Run oxlint, then ESLint on all files, one ESLint run per machine at a time (as CI does)
	@./scripts/lint.sh --full

lint-fix: $(ESLINT_PREREQS) ## Run oxlint --fix, then ESLint --fix on changed files (scripts/lint.sh --full --fix for all files)
	@./scripts/lint.sh --eslint --fix

lint-actions: lint-actionlint lint-zizmor ## Lint GitHub Actions workflows

lint-actionlint: ## Run actionlint on GitHub Actions workflows (uses shellcheck if installed)
	go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.7

lint-zizmor: ## Run zizmor security analysis on GitHub Actions workflows
	@./scripts/zizmor.sh --min-confidence high .

# Shell files to lint (excludes node_modules, build artifacts, .git)
# Prune any node_modules tree (not just ./node_modules) plus the removed mobile/
# prototype: upgraded checkouts may keep stale untracked leftovers there (e.g.
# CocoaPods .sh scripts under mobile/ios) that would otherwise be scanned.
# Also prune ./.venv: uv installs the pyproject.toml tools there, and their
# packages ship shell scripts and Dockerfiles.
SHELL_SRC_FILES := $(shell find . -not \( -path '*/.git/*' -o -path '*/node_modules/*' -o -path './mobile/*' -o -path './build/*' -o -path './dist/*' -o -path './release/*' -o -path './benchmarks/terminal_bench/.leaderboard_cache/*' -o -path './.venv/*' \) -type f -name '*.sh' 2>/dev/null)

lint-shellcheck: ## Run shellcheck on shell scripts
	@echo "Running shellcheck on $(words $(SHELL_SRC_FILES)) shell scripts..."
	@shellcheck --external-sources $(SHELL_SRC_FILES)

# Dockerfiles to lint (excludes node_modules, build artifacts, .git)
DOCKERFILES := $(shell find . -not \( -path '*/.git/*' -o -path '*/node_modules/*' -o -path './mobile/*' -o -path './build/*' -o -path './dist/*' -o -path './release/*' -o -path './benchmarks/terminal_bench/.leaderboard_cache/*' -o -path './.venv/*' \) -type f -name 'Dockerfile' 2>/dev/null)

lint-hadolint: ## Run hadolint on Dockerfiles
	@echo "Running hadolint on $(words $(DOCKERFILES)) Dockerfiles..."
	@hadolint $(DOCKERFILES)

pin-actions: ## Pin GitHub Actions to SHA hashes (requires GH_TOKEN or gh CLI)
	./scripts/pin-actions.sh .github/workflows/*.yml .github/actions/*/action.yml

ifeq ($(OS),Windows_NT)
typecheck: node_modules/.installed vscode/node_modules/.installed src/version.ts $(BUILTIN_AGENTS_GENERATED) $(BUILTIN_SKILLS_GENERATED) $(BUILTIN_WORKFLOWS_GENERATED) $(WORKFLOW_RUNTIME_SOURCES_GENERATED) ## Run TypeScript type checking (uses tsgo for 10x speedup)
	@# On Windows, use npm run because bun x doesn't correctly pass arguments
	@npm x concurrently -g \
		"$(TSGO) --noEmit" \
		"$(TSGO) --noEmit -p tsconfig.main.json" \
		"$(TSGO) --noEmit -p tsconfig.tooling.json"
else
typecheck: node_modules/.installed vscode/node_modules/.installed src/version.ts $(BUILTIN_AGENTS_GENERATED) $(BUILTIN_SKILLS_GENERATED) $(BUILTIN_WORKFLOWS_GENERATED) $(WORKFLOW_RUNTIME_SOURCES_GENERATED)
	@bun x concurrently -g \
		"$(TSGO) --noEmit" \
		"$(TSGO) --noEmit -p tsconfig.main.json" \
		"$(TSGO) --noEmit -p tsconfig.tooling.json"
endif

# tsconfig.tooling.json type-checks vscode/src (which needs the extension's own devDependencies,
# e.g. @types/vscode) and scripts/**/*.test.ts alongside the app sources.
vscode/node_modules/.installed: vscode/package.json vscode/bun.lock
	@$(MAKE) -C vscode node_modules/.installed

PERF_REPETITIONS ?= 3
.PHONY: perf-workspace-scale
perf-workspace-scale: build-main ## Benchmark workspace-scale startup, RPCs, and config I/O (Linux)
	@set -eu; fixtures=$$(mktemp -d); trap 'rm -rf "$$fixtures"' EXIT; \
	for spec in "realistic 1801 41 0.70 real-1801-a70 2" "realistic 1801 41 0 real-1801-a0 1" "realistic 546 41 0 real-546-a0 2" "minimal 1801 41 0.70 min-1801-a70 1" "realistic 50 5 0 real-50-a0 1"; do \
		read -r profile count projects archived label launches <<< "$$spec"; \
		root="$$fixtures/$$label"; \
		bun scripts/perf/workspace-scale/generate-fixture.ts --root "$$root" --workspaces "$$count" --projects "$$projects" --archived "$$archived" --profile "$$profile"; \
		bun scripts/perf/workspace-scale/config-micro.ts --root "$$root" --label "$$label"; \
		bun scripts/perf/workspace-scale/run-server-bench.ts --root "$$root" --label "$$label" --repetitions $(PERF_REPETITIONS) --launches "$$launches"; \
	done

.PHONY: perf-analyze
perf-analyze: node_modules/.installed ## Rank CPU-profile hotspots: PROFILES="<paths>" [BASELINE="<paths>"] [PERF_ANALYZE_ARGS="--top 40"]
	@if [ -z "$(strip $(PROFILES))" ]; then \
		echo 'Usage: make perf-analyze PROFILES="<paths>" [BASELINE="<paths>"] [PERF_ANALYZE_ARGS="--top 40 --map-dir dist"]' >&2; \
		exit 2; \
	fi
	@bun scripts/perf/analyzeProfiles.ts $(foreach path,$(BASELINE),--baseline $(path)) $(PERF_ANALYZE_ARGS) $(PROFILES)

check-deadcode: node_modules/.installed ## Check for potential dead code (manual only, not in static-check)
	@echo "Checking for potential dead code with ts-prune..."
	@echo "(Note: Some unused exports are legitimate - types, public APIs, entry points, etc.)"
	@echo ""
	@bun x ts-prune -i '(test|spec|mock|bench|debug|storybook)' \
		| grep -v "used in module" \
		| grep -v "src/App.tsx.*default" \
		| grep -v "src/types/" \
		| grep -v "telemetry/index.ts" \
		|| echo "✓ No obvious dead code found"

## Testing
.PHONY: test-codex-comments test-pr-checks test-required-superseded test-branch-sync-guard
test-codex-comments: ## Test Codex comment gates with offline GitHub fixtures
	@python3 scripts/check_codex_comments_test.py

test-pr-checks: ## Test PR check discovery, readiness and the PR state watcher with offline GitHub fixtures
	@python3 scripts/pr_checks_test.py
	@python3 scripts/watch_pr_state_test.py

test-required-superseded: ## Test the Required stand-down decision for cancelled duplicate PR runs
	@python3 scripts/required_superseded_test.py

test-branch-sync-guard: ## Test the wait_pr_* checkout guard against real git clones with offline GitHub fixtures
	@python3 scripts/branch_sync_guard_test.py

test-integration: node_modules/.installed build-main ## Run all tests (unit + integration)
	@bun test src
	@TEST_INTEGRATION=1 bun x jest tests

# The files in test-unit-ci.sh's isolated list fail when another test file shares their process
# (#7297), so they run one per process here too, as in CI. The two shared runs skip them.
test-unit: node_modules/.installed build-main ## Run unit tests
	@set -e; isolated="$$(./scripts/test-unit-ci.sh --list-isolated)"; ignores=(); \
	for f in $$isolated; do ignores+=("--path-ignore-patterns=$${f#./}"); done; \
	bun test src "$${ignores[@]}"; \
	bun test ./tests/ui/storybook/ ./tests/ui/domIsolation.test.ts ./vscode/src/ ./scripts/ "$${ignores[@]}"; \
	for f in $$isolated; do bun test "./$${f#./}"; done

# The host trap self-tests and the in-memory agent-loop proof, in their own bun process.
# tests/hostProof.bunfig.toml loads the trap before tests/setup.ts. *.hostProof.ts files are
# not *.test.ts, so `bun test src`, test-unit-ci.sh and Jest never run them. The ./ prefix
# matters: without it bun reads each path as a name filter and exits 1. HOME and XUM_ROOT
# are set before bun starts, because Bun caches homedir and the log sink opens at the first
# log call. The temp dir keeps the proof's writes out of the real home (#7209). The real bun
# binary is resolved first: a version-manager shim (mise) finds its tools under HOME.
test-host-proof: node_modules/.installed src/version.ts ## Host trap self-tests and the in-memory loop proof (own process)
	@T="$$(mktemp -d)" && mkdir -p "$$T/home" "$$T/root" && \
	  bun_bin="$$(bun -e 'process.stdout.write(process.execPath)')" && \
	  files="$$(find src -name '*.hostProof.ts' | LC_ALL=C sort | sed 's|^|./|')" && \
	  HOME="$$T/home" XUM_ROOT="$$T/root" "$$bun_bin" --config=./tests/hostProof.bunfig.toml test $$files; \
	  status=$$?; rm -rf "$$T"; exit $$status

# CI runs this once per shard; SHARD_INDEX/SHARD_TOTAL (env) pick the slice. See the script header.
test-unit-ci: node_modules/.installed build-main ## Run the CI unit suite with coverage (sharded via SHARD_INDEX/SHARD_TOTAL)
	@./scripts/test-unit-ci.sh

test: test-unit ## Alias for test-unit

test-watch: ## Run tests in watch mode
	@./scripts/test.sh --watch

test-coverage: ## Run tests with coverage
	@./scripts/test.sh --coverage


smoke-test: build ## Run smoke test on npm package
	@echo "Building npm package tarball..."
	@TARBALL=$$(./scripts/pack-npm-package.sh) || exit $$?; \
	echo "Running smoke test on $$TARBALL..."; \
	PACKAGE_TARBALL="$$TARBALL" ./scripts/smoke-test.sh && \
	CANONICAL_TARBALL="$$TARBALL" ./scripts/smoke-test-mux-compat.sh; \
	EXIT_CODE=$$?; \
	rm -f "$$TARBALL"; \
	exit $$EXIT_CODE

BUGBASH_REPROS ?= 1
test-e2e: ## Run end-to-end tests (Playwright, then the bug-bash repros unless BUGBASH_REPROS=0)
	@$(MAKE) build
	@XUM_E2E_LOAD_DIST=1 XUM_E2E_SKIP_BUILD=1 PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 bun x playwright test --project=electron $(PLAYWRIGHT_ARGS)
	@if [ "$(BUGBASH_REPROS)" != "0" ]; then $(MAKE) test-bugbash-repros; fi

test-e2e-perf: ## Run automated performance profiling scenarios
	@$(MAKE) build
	@# One worker: parallel Electron apps contend on CPU, so a scenario measures its neighbours' startup (#5209).
	@XUM_E2E_RUN_PERF=1 XUM_PROFILE_REACT=1 XUM_E2E_LOAD_DIST=1 XUM_E2E_SKIP_BUILD=1 PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 bun x playwright test --project=electron tests/e2e/scenarios/perf*.spec.ts --workers 1 $(PLAYWRIGHT_ARGS)

perf-tape-replay: ## Replay a synthetic session tape through the desktop app (perf.tapeReplay)
	@$(MAKE) build
	@XUM_E2E_RUN_PERF=1 XUM_PROFILE_REACT=1 XUM_E2E_LOAD_DIST=1 XUM_E2E_SKIP_BUILD=1 PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 bun x playwright test --project=electron tests/e2e/scenarios/perf.tapeReplay.spec.ts --workers 1 $(PLAYWRIGHT_ARGS)

## Distribution
dist: build ## Build distributable packages
	@bun x electron-builder --publish never

# Issue #3338: bun installs host-only optional deps, but electron-builder packages both mac
# architectures from one node_modules tree, which otherwise omits the x64 sharp runtime.
ensure-mac-sharp-runtime-deps: node_modules/.installed
	@bun install --frozen-lockfile --os=darwin --cpu=x64
	@bun install --frozen-lockfile --os=darwin --cpu=arm64
	@# Cross-arch installs repoint node_modules/.bin at the last-installed platform; a
	@# host-native install restores them and keeps the darwin packages added above.
	@bun install --frozen-lockfile
	@for dir in \
		node_modules/@img/sharp-darwin-x64 \
		node_modules/@img/sharp-libvips-darwin-x64 \
		node_modules/@img/sharp-darwin-arm64 \
		node_modules/@img/sharp-libvips-darwin-arm64; do \
		if [ ! -d "$$dir" ]; then \
			echo "Missing $$dir after platform installs. bun >= 1.3 is required because older versions silently ignore --os/--cpu." >&2; \
			exit 1; \
		fi; \
	done

# ELECTRON_ZIP_DIR (CI sets it, from setup-xum's electron-zip input) names the directory of the
# checksum-checked electron-v<version>-<platform>-<arch>.zip files. electron-builder then unpacks
# them and downloads nothing: its own download retries nothing, and a github.com 504 failed
# Build / Linux in five queue runs on 2026-11-08. The directory must hold the zip of every arch
# the call builds, or electron-builder looks for an unpacked Electron there and fails.
ELECTRON_DIST_FLAG = $(if $(ELECTRON_ZIP_DIR),-c.electronDist="$(ELECTRON_ZIP_DIR)")

dist-mac: build ## Build macOS distributables (x64 + arm64)
	@$(MAKE) --no-print-directory ensure-mac-sharp-runtime-deps
	@if [ -n "$$CSC_LINK" ]; then \
		echo "🔐 Code signing enabled - using unified build for correct yml..."; \
		bun x electron-builder --mac --x64 --arm64 --publish never $(ELECTRON_DIST_FLAG); \
	else \
		echo "Building macOS architectures in parallel..."; \
		bun x electron-builder --mac --x64 --publish never $(ELECTRON_DIST_FLAG) & pid1=$$! ; \
		bun x electron-builder --mac --arm64 --publish never $(ELECTRON_DIST_FLAG) & pid2=$$! ; \
		wait $$pid1 && wait $$pid2; \
	fi
	@# electron-updater skips an update when os.release() (the Darwin version) is below the
	@# yml's minimumSystemVersion. Electron 44 needs macOS 13 (Darwin 22), so macOS 12 users
	@# stay on the last release that still runs there instead of updating to one that won't start.
	@for f in release/*-mac.yml; do \
		[ -f "$$f" ] || continue; \
		grep -q '^minimumSystemVersion:' "$$f" || echo 'minimumSystemVersion: 22.0.0' >> "$$f"; \
	done
	@echo "✅ Both architectures built successfully"

# MAC_TARGETS narrows electron-builder's mac targets (e.g. MAC_TARGETS=dmg); empty keeps
# package.json's full list. PR CI builds only the DMG it uploads; the auto-update zip
# roughly doubles packaging time and is still built by merge-queue/main runs.
MAC_TARGETS ?=
dist-mac-x64: build ## Build macOS x64 distributable only
	@$(MAKE) --no-print-directory ensure-mac-sharp-runtime-deps
	@echo "Building macOS x64..."
	@bun x electron-builder --mac $(MAC_TARGETS) --x64 --publish never $(ELECTRON_DIST_FLAG)

dist-mac-arm64: build ## Build macOS arm64 distributable only
	@$(MAKE) --no-print-directory ensure-mac-sharp-runtime-deps
	@echo "Building macOS arm64..."
	@bun x electron-builder --mac $(MAC_TARGETS) --arm64 --publish never $(ELECTRON_DIST_FLAG)

install-mac-arm64: dist-mac-arm64 ## Build and install macOS arm64 app to /Applications
	@app_bundle="$$(bun -e 'import { resolveMacPackagedAppNames } from "./src/common/compat/macPackagedApp.ts"; import pkg from "./package.json"; process.stdout.write(resolveMacPackagedAppNames(pkg.build).appBundleName)')"; \
	echo "Installing $$app_bundle to /Applications..."; \
	rm -rf "/Applications/$$app_bundle"; \
	cp -R "release/mac-arm64/$$app_bundle" /Applications/; \
	echo "Installed $$app_bundle to /Applications"

dist-win: build ## Build Windows distributable
	@bun x electron-builder --win --publish never $(ELECTRON_DIST_FLAG)

dist-linux: build ## Build Linux distributable
	@bun x electron-builder --linux --publish never $(ELECTRON_DIST_FLAG)

dist-linux-arm64: build ## Build Linux arm64 distributable
	@bun x electron-builder --linux --arm64 --publish never $(ELECTRON_DIST_FLAG)

# MAC_ARCH=x64|arm64 validates a single-arch build (dist-mac-<arch>) instead of both.
check-mac-attach-file-runtime: ## Validate packaged macOS attach_file runtime assets (requires prior dist-mac build)
	@bun scripts/checkMacAttachFileRuntime.ts $(if $(MAC_ARCH),--arch $(MAC_ARCH))

check-appimage-icons: ## Validate AppImage icon structure (requires prior dist-linux build)
	@./scripts/check-appimage-icons.sh

## VS Code Extension (delegates to vscode/Makefile)

vscode-ext: ## Build VS Code extension (.vsix)
	@$(MAKE) -C vscode build

vscode-ext-install: ## Build and install VS Code extension locally
	@$(MAKE) -C vscode install

## Documentation
# The Mintlify CLI and its dependencies, as scripts/mintlify/bun.lock pins them. Bump mintlify
# there (`bun add mintlify@<version>` in that directory) and check the docs targets still run:
# 4.2.681 pulls @mintlify/auth-edge@0.0.36, which was unpublished from npm (404).
MINTLIFY := $(CURDIR)/scripts/mintlify/node_modules/.bin/mintlify

scripts/mintlify/node_modules/.installed: scripts/mintlify/package.json scripts/mintlify/bun.lock
	@cd scripts/mintlify && bun install --frozen-lockfile --ignore-scripts
	@touch $@

docs-server: scripts/mintlify/node_modules/.installed ## Serve documentation locally (Mintlify dev server)
	@cd docs && $(MINTLIFY) dev

check-docs-links: scripts/mintlify/node_modules/.installed ## Check documentation for broken links
	@echo "🔗 Checking documentation links..."
	@cd docs && $(MINTLIFY) broken-links

check-code-docs-links: ## Validate code references to docs paths
	@./scripts/check-code-docs-links.sh

## Storybook
storybook: node_modules/.installed src/version.ts ## Start Storybook development server
	$(check_node_version)
	@bun x storybook dev -p 6006 $(STORYBOOK_OPEN_FLAG)

storybook-run: node_modules/.installed src/version.ts ## Run CMD with a ready Storybook dev server (reuses STORYBOOK_PORT, default 6006)
	$(check_node_version)
	@bun scripts/with-storybook.ts --port $(or $(STORYBOOK_PORT),6006) -- $(CMD)

storybook-build: node_modules/.installed src/version.ts ## Build static Storybook
	$(check_node_version)
	@bun x storybook build

storybook-flake-check: node_modules/.installed src/version.ts ## Replay Pixel captures to find nondeterministic stories (STORYBOOK_FLAKE_ARGS='--files a.stories.tsx --runs 5')
	$(check_node_version)
	@# Always rebuild: a stale storybook-static/ would vouch for code that is no longer there.
	@bun x storybook build
	@# Node, not Bun: relaunching Playwright under Bun intermittently hangs.
	@node scripts/storybook-flake-check.mjs $(STORYBOOK_FLAKE_ARGS)

capture-readme-screenshots: node_modules/.installed src/version.ts ## Capture README screenshots from running Storybook
	@echo "Capturing README screenshots from Storybook (must be running on port 6006)..."
	@bun run scripts/capture-readme-screenshots.ts

test-storybook: node_modules/.installed ## Run Storybook interaction tests (requires Storybook to be running or built)
	$(check_node_version)
	@# Storybook story transitions can exceed Jest's default 15s timeout on loaded CI runners.
	@bun x test-storybook --testTimeout 30000

# The runner opens the Storybook page once for every story file it is given, so only the files
# that name a tag are visited.
WEBKIT_STORY_FILES = $(shell grep -rlF -e '"webkit"' -e '"paint-check"' src/browser --include='*.stories.tsx')

test-storybook-webkit: node_modules/.installed ## Run the stories tagged "webkit" or "paint-check" in WebKit, which sizes SVG and CSS zoom unlike Chromium (requires Storybook to be running or built)
	$(check_node_version)
	@test -n "$(WEBKIT_STORY_FILES)" || { echo "No story has the webkit or paint-check tag"; exit 1; }
	@# paint-fixture stories are built to fail or to pass on purpose, so only test-storybook-paint-fixtures runs them.
	@bun x test-storybook --browsers webkit --includeTags webkit paint-check --excludeTags paint-fixture --testTimeout 30000 $(WEBKIT_STORY_FILES)

test-storybook-paint-fixtures: node_modules/.installed ## Prove the paint-check runner's guards still fire, with stories built to trip them (requires Storybook to be running or built; STORYBOOK_URL, default http://127.0.0.1:6006)
	$(check_node_version)
	@bun scripts/check-paint-check-fixtures.ts

storybook-budget: node_modules/.installed ## Enforce the Pixel snapshot budget (requires Storybook served; STORYBOOK_URL, default http://127.0.0.1:6006)
	$(check_node_version)
	@# Node, not Bun: it drives Playwright like pixel-storybook (see storybook-flake-check).
	@node scripts/check-storybook-snapshot-budget.mjs --url $(or $(STORYBOOK_URL),http://127.0.0.1:6006)

## Benchmarks
bench: node_modules/.installed src/version.ts ## Run *.bench.ts microbenchmarks (BENCH=<substring|glob>, RUNTIME=node|bun, JSON=<path>)
	@bun scripts/perf/bench.ts --runtime $(or $(RUNTIME),node) $(if $(JSON),--json '$(JSON)') $(if $(BENCH),'$(BENCH)')

bench-compare: node_modules/.installed src/version.ts ## Compare *.bench.ts results, base vs working tree (BENCH=<filter>, BASE=<ref>, ROUNDS=10, RUNTIME=node|bun)
	@bun scripts/perf/benchCompare.ts --bench '$(BENCH)' --runtime $(or $(RUNTIME),node) --rounds $(or $(ROUNDS),10) $(if $(BASE),--base '$(BASE)')

# Agent loop refactor tripwire data. Gates call the script directly: make reports any failure as 2.
test-loop-baseline: node_modules/.installed src/version.ts ## Time the loop test files (RUNS=10, FILTER=<substring>, JOBS=6, BASE=<ref> compares)
	@bun scripts/perf/loopTestBaseline.ts --runs $(or $(RUNS),10) --jobs $(or $(JOBS),6) $(if $(FILTER),--filter '$(FILTER)') $(if $(BASE),--base '$(BASE)')

first-load-js: ## Report first-load JS bytes of dist/ (run make build-renderer first)
	@bun scripts/perf/firstLoadJs.ts dist

page-timing: node_modules/.installed ## Paired mobile UCS/IR timing of two built trees (PAGE_TIMING_ARGS; see scripts/perf/pageTiming.ts)
	@node --import tsx scripts/perf/pageTiming.ts $(PAGE_TIMING_ARGS)

first-run-view-parity: node_modules/.installed ## Static vs live first-run view boxes and screenshots, 4 widths x 2 themes (FIRST_RUN_VIEW_PARITY_ARGS; see scripts/perf/firstRunViewParity.ts)
	@node --import tsx scripts/perf/firstRunViewParity.ts $(FIRST_RUN_VIEW_PARITY_ARGS)

generate-phone-chrome: build-main build-renderer build-static ## Capture the phone skeleton of the static workspace view from the live page (see scripts/perf/generatePhoneChrome.ts)
	@bun scripts/perf/generatePhoneChrome.ts $(PHONE_CHROME_ARGS)

check-phone-chrome: node_modules/.installed ## Fail when the built live phone workspace page (run `make build` first) drifted from the checked-in skeleton
	@bun scripts/perf/generatePhoneChrome.ts --check $(PHONE_CHROME_ARGS)

benchmark-terminal: ## Run Terminal-Bench 2.0 with Harbor (use TB_DATASET/TB_CONCURRENCY/TB_TIMEOUT/TB_ENV/TB_MODEL/TB_ARGS to customize)
	@# Harbor and its Daytona SDK come from the harbor group in pyproject.toml; bump them there.
	@# Harbor removed --task-name, so keep smoke-test task filtering on the current dataset filter flag.
	@TB_DATASET=$${TB_DATASET:-terminal-bench@2.0}; \
	TB_TIMEOUT=$${TB_TIMEOUT:-1800}; \
	TB_CONCURRENCY=$${TB_CONCURRENCY:-4}; \
	ENV_FLAG=$${TB_ENV:+--env $$TB_ENV}; \
	MODEL_FLAG=$${TB_MODEL:+-m $$TB_MODEL}; \
	TASK_NAME_FLAGS=""; \
	if [ -n "$${TB_TASK_NAMES:-}" ]; then \
		for task_name in $$TB_TASK_NAMES; do \
			TASK_NAME_FLAGS="$$TASK_NAME_FLAGS --include-task-name $$task_name"; \
		done; \
	fi; \
	echo "Using timeout: $$TB_TIMEOUT seconds"; \
	echo "Running Terminal-Bench with dataset $$TB_DATASET (concurrency: $$TB_CONCURRENCY)"; \
	export MUX_TIMEOUT_MS=$$((TB_TIMEOUT * 1000)); \
	uv run --locked --only-group harbor python -c 'import importlib.metadata as m; print("Resolved Harbor package:", m.version("harbor")); print("Resolved Daytona package:", m.version("daytona"))'; \
	uv run --locked --only-group harbor harbor run \
		--dataset "$$TB_DATASET" \
		--agent-import-path benchmarks.terminal_bench.mux_agent:MuxAgent \
		--agent-kwarg timeout=$$TB_TIMEOUT \
		--n-concurrent $$TB_CONCURRENCY \
		$$ENV_FLAG \
		$$MODEL_FLAG \
		$$TASK_NAME_FLAGS \
		$${TB_ARGS:-}

## Clean
clean: ## Clean build artifacts
	@echo "Cleaning build artifacts..."
	@rm -rf dist release build/icon.icns build/icon.png
	@echo "Done!"

## Startup Performance Checks
# Walks the static import graph of the startup entry points (no build needed).
# The analyzer's fixture tests run first so a broken guard cannot pass vacuously.
check-startup-imports: node_modules/.installed src/version.ts $(BUILTIN_AGENTS_GENERATED) $(BUILTIN_SKILLS_GENERATED) $(WORKFLOW_RUNTIME_SOURCES_GENERATED) ## Check that heavy packages stay off the eager startup import path
	@bun test ./scripts/check-startup-imports.test.ts
	@bun scripts/check-startup-imports.ts

# Post-build complement to check-startup-imports (#4423): launches package.json `main`
# (the CLI shim, which routes to desktop main) like `electron .` in plain Node with a
# stubbed `electron` and fails if a banned package is in require.cache.
# Catches what the static walk cannot (module-scope import(), computed require()).
# Needs a build, so it runs in CI's Smoke / Server job rather than static-check.
check-startup-imports-runtime: build-main ## Check package.json main (CLI shim -> desktop main) loads no banned package at startup
	@bun scripts/check-startup-imports-runtime.ts

# ~3 s: compiles only the hot-path files listed in the script, so it runs in static-check.
check-react-compiler: node_modules/.installed ## Fail when a hot renderer component stops compiling under React Compiler
	@bun scripts/check_react_compiler_coverage.ts

# Parallel build optimization - these can run concurrently
.NOTPARALLEL: build-main  # TypeScript can handle its own parallelism