# AstraBox Community — developer entrypoints.
#
# These targets are the human-facing twins of what CI runs:
#   * `make test`             == the .github/workflows/ci.yml unit/lint/typecheck job
#                                (ruff + mypy + non-e2e pytest, + frontend
#                                 tsc, build & vitest) — no Docker daemon and no secret;
#                                the pytest half needs ASTRABOX_TEST_POSTGRES_URL.
#   * `make e2e`              == the .github/workflows/e2e.yml job (build the agent
#                                image, then the curl smoke + the Playwright happy
#                                path) — needs Docker + the operator LLM key (.env).
#   * `make dev`             — boot the local backend+frontend stack (scripts/dev.sh).
#   * `make build-agent-image`— build the in-sandbox astrabox/sandbox-claude-code:latest image.
#   * `make k8s-testbed-up`   — throwaway k3s + the OpenSandbox controller, so the
#                               sandbox server's kubernetes runtime can be exercised
#                               rather than assumed — needs passwordless sudo.
#
# Override the interpreter / image knobs on the command line, e.g.
#   make build-agent-image CLAUDE_CODE_VERSION=2.1.220
#   make test PY=python3.12

SHELL := /usr/bin/env bash
.DEFAULT_GOAL := help

# ── tools / knobs ────────────────────────────────────────────────────────────
VENV            ?= .venv
PY              ?= $(VENV)/bin/python
NODE_TOOLCHAIN   ?= python3 scripts/node-toolchain.py
RUFF            ?= $(PY) -m ruff
MYPY            ?= $(PY) -m mypy
PYTEST          ?= $(PY) -m pytest
PKG             ?= astrabox

AGENT_IMAGE         ?= astrabox/sandbox-claude-code:latest
ASSISTANT_IMAGE     ?= astrabox/sandbox-hermes:latest
DSH_IMAGE           ?= astrabox/sandbox-deepseek-harness:latest
CODEX_IMAGE         ?= astrabox/sandbox-codex:latest
PI_IMAGE            ?= astrabox/sandbox-pi:latest
# An explicit execd input belongs to the caller; build only the implicit default.
_EXECD_PREREQUISITE := $(if $(filter undefined,$(origin EXECD_IMAGE)),build-execd-image)
EXECD_IMAGE         ?= astrabox/execd:latest
WORKSPACE_MOUNTER_IMAGE ?= astrabox/workspace-mounter:latest
SERVER_IMAGE        ?= astrabox/server:latest
# `--build-context <stage>=DIR` flags for images with checksum-pinned source
# stages. Empty for a standalone build, which downloads each pinned source in its
# own stage; a build host with a verified cache passes it here instead
# (scripts/pinned-build-sources.py).
DOCKER_BUILD_CONTEXTS ?=
ALL_IN_ONE_IMAGE    ?= astrabox/all-in-one:latest
# Kubernetes nodes using IfNotPresent need a new tag for each image build;
# reusing `:latest` can leave a node serving cached content. The commit-derived
# tag also makes the deployed source identifiable from `docker images`.
# Source copies without `.git` use a timestamp so separate builds remain
# distinguishable.
IMAGE_TAG           ?= $(shell git rev-parse --short=12 HEAD 2>/dev/null && { git diff --quiet 2>/dev/null || echo -dirty; } || date -u +nogit-%Y%m%d%H%M%S)
REGISTRY            ?=
CLAUDE_CODE_VERSION ?= 2.1.308
SANDBOX_BASE_IMAGE  ?= ghcr.io/agent-infra/sandbox:1.11.0
NPM_REGISTRY        ?= https://registry.npmjs.org/

.PHONY: help install install-py install-web install-channel-gateway dev test test-py lint typecheck fmt-check check-e2e-collection \
        check-comments check-comments-report check-i18n check-upstream check-api-client check-all-in-one check-dockerfile-modes check-sandbox-seam \
        check-env-registry check-http-surface check-background-tasks check-release \
        test-web test-channel-gateway test-layout utilisation build-web build-dist e2e e2e-smoke e2e-browser e2e-live \
        build-agent-image build-assistant-image build-dsh-image build-codex-image build-pi-image build-execd-image build-workspace-mounter-image build-all-in-one-image clean \
        k8s-testbed-up k8s-testbed-status k8s-testbed-down k8s-testbed-purge

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

# ── install ──────────────────────────────────────────────────────────────────
install: install-py install-web install-channel-gateway ## Install Python, web, and channel-gateway dependencies.

# [sandbox-server] is NOT optional for a developer checkout, even though it is an
# optional extra of the package: every launch path (`make dev`, `make e2e-smoke`,
# scripts/dev.sh, scripts/e2e_smoke.sh) runs `python -m astrabox.deploy.onebox`,
# which starts the bundled OpenSandbox lifecycle server in-process and fails loud
# without it. The CI unit lane deliberately installs `.[dev]` alone — it never
# launches the stack — and that is what keeps `import astrabox` free of the extra.
install-py: ## Create .venv (if missing) and install the package editable with [dev,sandbox-server].
	@test -x "$(PY)" || python3 -m venv "$(VENV)"
	$(PY) -m pip install -U pip
	$(PY) -m pip install -e '.[dev,sandbox-server]'

# scripts/api-codegen is its own npm package because openapi-typescript emits
# through the TypeScript compiler API and the console is on typescript@7, the Go
# port, which ships none — see scripts/check_api_client.py.
install-web: ## npm ci for every web/test package (lockfile-exact).
	$(NODE_TOOLCHAIN) npm --prefix frontend ci
	$(NODE_TOOLCHAIN) npm --prefix tests/e2e-ui ci
	$(NODE_TOOLCHAIN) npm --prefix e2e ci
	$(NODE_TOOLCHAIN) npm --prefix scripts/api-codegen ci

install-channel-gateway: ## npm ci for the bundled concrete channel adapters.
	$(NODE_TOOLCHAIN) npm --prefix channel-gateway ci --ignore-scripts

# ── dev ──────────────────────────────────────────────────────────────────────
dev: ## Boot the local dev stack: backend (:8000) + frontend (:5173). Ctrl-C stops.
	./scripts/dev.sh

# ── test (the CI unit/lint/typecheck job — no Docker daemon, no secret) ──────
test: check-comments check-i18n check-errors check-env-registry check-http-surface check-background-tasks check-release check-credential-seam check-sandbox-seam check-all-in-one check-dockerfile-modes check-api-client lint typecheck test-py test-web ## Full unit gate: static checks + ruff + mypy + pytest + web build/vitest.

test-py: ## Race and security unit tests (the live `e2e` mark is deselected). Needs ASTRABOX_TEST_POSTGRES_URL: a PostgreSQL role that may create databases.
	$(NODE_TOOLCHAIN) $(PYTEST)

lint: ## ruff check (E402/F401/F811/F821/F841 grandfathered tree-wide — see pyproject).
	$(RUFF) check $(PKG) scripts tests

typecheck: ## mypy over the package (lenient config — see [tool.mypy]).
	$(MYPY) $(PKG)

fmt-check: ## Advisory ruff format check; not part of the repository gate.
	-$(RUFF) format --check $(PKG)

screenshots: ## Recapture assets/screenshots/ from a live deployment. Needs ASTRABOX_E2E_BASE_URL, and ASTRABOX_E2E_SCREENSHOT_MODEL naming a model the deployment holds a credential for.
	$(NODE_TOOLCHAIN) npm --prefix tests/e2e-ui run e2e -- console-screenshots

check-comments: ## Enforce the CONTRIBUTING.md comment rules against the reviewed zero baseline.
	$(PY) scripts/check_comment_style.py

check-comments-report: ## Print every current comment-style violation, grouped by class.
	$(PY) scripts/check_comment_style.py --report

check-i18n: ## Check console locale JSON, EN/ZH key parity, plurals, and placeholders.
	$(PY) scripts/check_i18n.py

check-errors: ## Every raised error code has a registry row, against the shrinking baseline.
	$(PY) scripts/check_error_registry.py

check-env-registry: ## Every env var read has a registry row and every row a read; docs/configuration.md is fresh.
	$(PY) scripts/check_env_registry.py

check-http-surface: ## Routes are unique and deterministic, the OpenAPI snapshot is current, every _svc() call resolves.
	$(PY) scripts/check_http_surface.py

check-background-tasks: ## Every created asyncio task is held or awaited.
	$(PY) scripts/check_background_tasks.py

check-release: ## Default images are published by release.yml, Compose names the same registry, storage providers are discoverable.
	$(PY) scripts/check_release.py

check-credential-seam: ## Credential machinery stays behind the egress seam, against the shrinking baseline.
	$(PY) scripts/check_credential_seam.py

check-sandbox-seam: ## Platform code imports no sandbox backend's SDK, provider package or server launcher.
	$(PY) scripts/check_sandbox_seam.py

check-all-in-one: ## Every Compose server setting is refused or passed through by the all-in-one image, whose edges match Compose's.
	$(PY) scripts/check_all_in_one.py

check-dockerfile-modes: ## Every COPY/ADD from the build context sets its files' mode, so an image does not depend on the builder's umask.
	$(PY) scripts/check_dockerfile_modes.py

check-api-client: ## frontend/src/api/schema.d.ts is byte-identical to what the committed OpenAPI snapshot generates. Needs `npm --prefix scripts/api-codegen ci` (make install-web).
	$(PY) scripts/check_api_client.py

check-upstream: ## Every vendored ui/ and ai-elements/ file still matches its registry. Needs the network; NOT in `make test` for that reason — run it when re-vendoring, and when upstream moves.
	$(PY) scripts/check_upstream.py

test-web: test-channel-gateway build-web typecheck-e2e ## Channel gateway + frontend typecheck (tsc --noEmit) + prod build + interaction-state, palette and failure-voice checks + vitest unit run + e2e spec typecheck.
	$(PY) scripts/check_interaction_states.py
	$(PY) scripts/check_palette.py
	$(PY) scripts/check_failure_voice.py
	$(NODE_TOOLCHAIN) npm --prefix frontend test

test-channel-gateway: ## Node tests for provider schemas and the bundled adapter runtime.
	$(NODE_TOOLCHAIN) npm --prefix channel-gateway test

typecheck-e2e: ## tsc --noEmit over both Playwright suites, plus the lane inventories. Playwright transpiles specs without typechecking them, so a wrong-arity API call is otherwise found on the testbed.
	$(NODE_TOOLCHAIN) npm --prefix tests/e2e-ui run typecheck
	$(NODE_TOOLCHAIN) npm --prefix e2e run typecheck
	$(PY) scripts/check_e2e_collection.py

check-e2e-collection: ## Ask Playwright what each e2e lane holds and compare to the frozen contract. Needs the e2e-ui dependency tree (make install-web).
	$(PY) scripts/check_e2e_collection.py

test-layout: ## Console layout gate across 4 viewports (stubbed /api — no backend, no Docker, no key). Needs chromium: `npm --prefix e2e run install:browser`.
	$(NODE_TOOLCHAIN) npm --prefix e2e run test:layout

utilisation: ## Report how much of the window each page uses, at 1280/1440/1920/2560. Asserts nothing — read it when adding or widening a page.
	$(NODE_TOOLCHAIN) npm --prefix e2e run utilisation

build-web: ## tsc --noEmit && vite build for the console.
	$(NODE_TOOLCHAIN) npm --prefix frontend run build

# ── e2e (needs Docker + the operator LLM key in .env) ────────────────────────
e2e: build-server-image build-agent-image e2e-smoke e2e-browser ## Full live e2e: build images, curl smoke, Playwright happy-path.

e2e-smoke: ## Headless curl-level live-turn proof (scripts/e2e_smoke.sh; asserts a real text-delta).
	./scripts/e2e_smoke.sh

e2e-browser: ## Browser happy-path through the real UI (e2e/ Playwright; boots its own stack).
	$(NODE_TOOLCHAIN) npm --prefix e2e ci
	$(NODE_TOOLCHAIN) npm --prefix e2e run install:browser
	$(NODE_TOOLCHAIN) npm --prefix e2e run test:happy

# The live pytest suite against a deployment that is ALREADY running — set
# ASTRABOX_E2E_BASE_URL to it. Five workers because these tests wait on a real
# model and a real cluster, not on CPU.
#
# scripts/e2e_live.sh, not a bare pytest, because `maxfail` only stops pytest
# handing out NEW tests: the workers already running keep going, and a live test
# can sit until its fixed 180 s timeout. The script kills the run at the first failed
# report and cleans up nothing, so the scene is there when you look.
E2E_WORKERS ?= 5
e2e-live: ## Main PostgreSQL + Agent live pytest lane (5 workers; first-red; keeps its sandbox).
	E2E_WORKERS=$(E2E_WORKERS) ./scripts/e2e_live.sh

# ── the Kubernetes testbed (scripts/k8s-testbed.sh) ──────────────────────────
# Stands up a throwaway k3s + the OpenSandbox CONTROLLER, so the sandbox server's
# kubernetes runtime can be exercised rather than assumed. The server itself is
# NOT installed into the cluster — AstraBox runs it, exactly as on one host.
# Needs passwordless sudo (it installs k3s). See docs/providers/opensandbox.md.

k8s-testbed-up: ## Bring up k3s + the OpenSandbox controller + the sandbox namespace, then print the env to set.
	./scripts/k8s-testbed.sh up

k8s-testbed-status: ## What the testbed is actually running (cluster, controller, CRDs, live sandboxes).
	./scripts/k8s-testbed.sh status

k8s-testbed-down: ## Remove the controller, its CRDs and both namespaces. Refuses while sandbox resources still exist.
	./scripts/k8s-testbed.sh down

k8s-testbed-purge: ## k8s-testbed-down, then uninstall k3s itself.
	./scripts/k8s-testbed.sh purge

# ── images ───────────────────────────────────────────────────────────────────
build-execd-image: ## Build the pinned native filesystem transport with streaming uploads.
	docker build -t $(EXECD_IMAGE) $(DOCKER_BUILD_CONTEXTS) -f containers/execd/Dockerfile .

build-agent-image build-dsh-image build-codex-image build-pi-image: $(_EXECD_PREREQUISITE)

build-agent-image: ## Build the sandbox agent image; stop with an error if the pinned Claude CLI or runtime service is missing.
	docker build -t $(AGENT_IMAGE) \
	  --build-arg SANDBOX_EXECD_IMAGE=$(EXECD_IMAGE) \
	  --build-arg CLAUDE_CODE_VERSION=$(CLAUDE_CODE_VERSION) \
	  --build-arg SANDBOX_BASE_IMAGE=$(SANDBOX_BASE_IMAGE) \
	  --build-arg NPM_REGISTRY=$(NPM_REGISTRY) \
	  -f containers/sandbox-claude-code/Dockerfile \
	  .

build-assistant-image: ## Build the in-sandbox Hermes image the assistant engine runs in.
	# The Hermes pin stays in containers/sandbox-hermes/Dockerfile rather than
	# being passed from here: a second copy of the version is a second thing to
	# forget. The base image IS passed, because the assistant and claude-code
	# boxes must share it.
	docker build -t $(ASSISTANT_IMAGE) $(DOCKER_BUILD_CONTEXTS) \
	  --build-arg SANDBOX_BASE_IMAGE=$(SANDBOX_BASE_IMAGE) \
	  -f containers/sandbox-hermes/Dockerfile \
	  .

build-dsh-image: ## Build the in-sandbox DeepSeek Harness runtime image.
	docker build -t $(DSH_IMAGE) \
	  --build-arg SANDBOX_EXECD_IMAGE=$(EXECD_IMAGE) \
	  --build-arg SANDBOX_BASE_IMAGE=$(SANDBOX_BASE_IMAGE) \
	  -f containers/sandbox-deepseek-harness/Dockerfile \
	  .

build-codex-image: ## Build the in-sandbox Codex app-server runtime image.
	docker build -t $(CODEX_IMAGE) \
	  --build-arg SANDBOX_EXECD_IMAGE=$(EXECD_IMAGE) \
	  --build-arg SANDBOX_BASE_IMAGE=$(SANDBOX_BASE_IMAGE) \
	  -f containers/sandbox-codex/Dockerfile \
	  .

build-pi-image: ## Build the in-sandbox pi RPC runtime image.
	docker build -t $(PI_IMAGE) \
	  --build-arg SANDBOX_EXECD_IMAGE=$(EXECD_IMAGE) \
	  --build-arg SANDBOX_BASE_IMAGE=$(SANDBOX_BASE_IMAGE) \
	  --build-arg NPM_REGISTRY=$(NPM_REGISTRY) \
	  -f containers/sandbox-pi/Dockerfile \
	  .

build-workspace-mounter-image: ## Build the host-side mergerfs workspace helper, outside agent sandboxes.
	docker build -t $(WORKSPACE_MOUNTER_IMAGE) $(DOCKER_BUILD_CONTEXTS) -f containers/workspace-mounter/Dockerfile .

build-server-image: ## Build the deployment image (console + backend). Slow by design: it builds the frontend.
	docker build --build-arg NODE_VERSION=$$(cat .nvmrc) -t $(SERVER_IMAGE) -f containers/server/Dockerfile .

build-all-in-one-image: build-server-image ## Build the single-container image FROM the server image just built: embedded PostgreSQL 17 and Valkey.
	docker build --build-arg SERVER_IMAGE=$(SERVER_IMAGE) -t $(ALL_IN_ONE_IMAGE) -f containers/all-in-one/Dockerfile .

# Content-addressed publish for anything a CLUSTER pulls. Tagging by tree state
# makes IfNotPresent safe: every changed tree receives a distinct tag, so a node
# cannot serve a stale image for the requested tag.
push-images: ## Tag every cluster-pulled image $(IMAGE_TAG) and push to $$REGISTRY (e.g. REGISTRY=10.0.0.5:5000).
	@test -n "$(REGISTRY)" || { echo "push-images: set REGISTRY=host:port"; exit 2; }
	docker tag $(EXECD_IMAGE)     $(REGISTRY)/astrabox/execd:$(IMAGE_TAG)
	docker tag $(AGENT_IMAGE)     $(REGISTRY)/astrabox/sandbox-claude-code:$(IMAGE_TAG)
	docker tag $(ASSISTANT_IMAGE) $(REGISTRY)/astrabox/sandbox-hermes:$(IMAGE_TAG)
	docker tag $(DSH_IMAGE)       $(REGISTRY)/astrabox/sandbox-deepseek-harness:$(IMAGE_TAG)
	docker tag $(CODEX_IMAGE)     $(REGISTRY)/astrabox/sandbox-codex:$(IMAGE_TAG)
	docker tag $(PI_IMAGE)        $(REGISTRY)/astrabox/sandbox-pi:$(IMAGE_TAG)
	docker tag $(WORKSPACE_MOUNTER_IMAGE) $(REGISTRY)/astrabox/workspace-mounter:$(IMAGE_TAG)
	docker tag $(SERVER_IMAGE)    $(REGISTRY)/astrabox/server:$(IMAGE_TAG)
	docker push $(REGISTRY)/astrabox/execd:$(IMAGE_TAG)
	docker push $(REGISTRY)/astrabox/sandbox-claude-code:$(IMAGE_TAG)
	docker push $(REGISTRY)/astrabox/sandbox-hermes:$(IMAGE_TAG)
	docker push $(REGISTRY)/astrabox/sandbox-deepseek-harness:$(IMAGE_TAG)
	docker push $(REGISTRY)/astrabox/sandbox-codex:$(IMAGE_TAG)
	docker push $(REGISTRY)/astrabox/sandbox-pi:$(IMAGE_TAG)
	docker push $(REGISTRY)/astrabox/workspace-mounter:$(IMAGE_TAG)
	docker push $(REGISTRY)/astrabox/server:$(IMAGE_TAG)
	@echo
	@echo "pushed $(IMAGE_TAG) — point the deployment at it:"
	@echo "  ASTRABOX_AGENT_IMAGE=$(REGISTRY)/astrabox/sandbox-claude-code:$(IMAGE_TAG)"
	@echo "  ASTRABOX_WORKSPACE_MOUNTER_IMAGE=$(REGISTRY)/astrabox/workspace-mounter:$(IMAGE_TAG)"
	@echo "  assistant environment runtime_template_name=$(REGISTRY)/astrabox/sandbox-hermes:$(IMAGE_TAG)"
	@echo "  dsh environment runtime_template_name=$(REGISTRY)/astrabox/sandbox-deepseek-harness:$(IMAGE_TAG)"
	@echo "  codex environment runtime_template_name=$(REGISTRY)/astrabox/sandbox-codex:$(IMAGE_TAG)"
	@echo "  pi environment runtime_template_name=$(REGISTRY)/astrabox/sandbox-pi:$(IMAGE_TAG)"

# ── Source-mounted deployment loop ───────────────────────────────────────────
# scripts/dev.sh mounts this checkout over the installed package while keeping
# the Compose database and sandbox-edge topology. Rebuild the server
# image only when dependencies change; Python source changes reload in place.
run-mounted: ## Run the source-mounted backend on :8088 using the maintained Compose topology.
	@test -f .env || { echo "run-mounted: needs .env (see .env.example)"; exit 2; }
	ASTRABOX_DEV_BACKEND_ONLY=1 \
	ASTRABOX_DEV_BACKEND_PORT=8088 \
	ASTRABOX_SERVER_IMAGE=$(SERVER_IMAGE) \
	./scripts/dev.sh

build-dist: build-web ## Release wheel+sdist WITH the console packaged (astrabox/_frontend_dist).
	rm -rf astrabox/_frontend_dist dist
	cp -r frontend/dist astrabox/_frontend_dist
	$(PY) -m build
	@unzip -l dist/*.whl | grep -q "astrabox/_frontend_dist/index.html" \
	  || { echo "build-dist: wheel is MISSING the packaged console (astrabox/_frontend_dist)"; exit 1; }
	@unzip -l dist/*.whl | grep -q "astrabox/py.typed" \
	  || { echo "build-dist: wheel is MISSING the PEP 561 marker (astrabox/py.typed)"; exit 1; }
	@tar tzf dist/*.tar.gz | grep -q "_frontend_dist/index.html" \
	  || { echo "build-dist: sdist is MISSING the packaged console"; exit 1; }
	@echo "build-dist: console packaged OK ($$(unzip -l dist/*.whl | grep -c _frontend_dist) files)"

# ── housekeeping ─────────────────────────────────────────────────────────────
clean: ## Remove build/test caches + web dist dirs (does NOT touch .venv or state).
	rm -rf .pytest_cache .ruff_cache .mypy_cache **/__pycache__ \
	       frontend/dist astrabox/_frontend_dist dist \
	       e2e/test-results e2e/playwright-report