Local verification

make local-verification is the cross-package completion gate for Refract. It runs the same checklist agents and humans use before merging backend or multi-package work. How each step executes depends on an explicit exec backend, not on detecting Cursor, GitHub Actions, or “cloud.”

Pipeline (same steps everywhere)

migrate-up
build-lint-deps (shared + tooling-eslint-refract)
lint-all
build-all
test-all
gql-codegen
gql-codegen-dirty-tree (fail if generated files are uncommitted — same check as CI codegen-verification)
verify-production-browser-static (production Dockerfile build + marketing route smoke — same as CI production-browser-static-verify)

Step order differs by backend:

Backend	Order (why)
compose	migrate → build-lint-deps → … (stack already has built packages in the container)
native	build-lint-deps → migrate → … (`ts-node` migrate needs `shared` types on the host)

Choosing an exec backend

Value	When to use	How steps run
`compose` (default if unset)	Laptop with `make start` / Compose stack	Nested `make` targets → `docker compose exec backend …`
`native`	Cloud agents, CI-like VMs, host Node + local Postgres/Redis	Host `pnpm` / `ts-node` with test env (mirrors integration.yml service layout)

Set via environment or Make override:

# Default — Docker Compose (unchanged local UX)
make local-verification

# Explicit compose
REFRACT_EXEC_BACKEND=compose make local-verification

# Native (host pnpm for lint/test/codegen; Docker still required for the prod smoke)
REFRACT_EXEC_BACKEND=native make local-verification

# Same as native via Make override
make local-verification EXEC_BACKEND=native

Invalid values fail fast in the Makefile and again in exec_backend_validate. There is no auto-detection of Cursor Cloud or GITHUB_ACTIONS. Harnesses declare the backend once (e.g. Cursor Cloud env: REFRACT_EXEC_BACKEND=native).

Native prerequisites

Node + pnpm on the host (packageManager in root package.json).
Postgres and Redis on localhost (defaults: localhost:5432, redis://localhost:6379, DB test_db, user/password postgres/password). Env vars can override — see scripts/shell/lib/verification-test-env.sh.
Writable /shared for portal GraphQL codegen (apps/portal/codegen.yml reads /shared/template.schema.graphql). One-time:
sudo mkdir -p /shared && sudo chmod 777 /shared
Docker for verify-production-browser-static (production image build + route smoke). The gate starts compose rds / memory when they are not already running.
Optional: REFRACT_VERIFY_SKIP_INSTALL=1 after Compose migrator (or an earlier install) already populated node_modules. Skips host pnpm install --frozen-lockfile (important when root node_modules is root-owned from Docker).

Typical Cloud / agent setup:

docker compose up -d rds memory   # DB + Redis; backend container not required for this gate
export REFRACT_EXEC_BACKEND=native
export REFRACT_VERIFY_SKIP_INSTALL=1
make local-verification

Scoped make test / make lint / make build still use Docker by default; only local-verification honors the native backend today.

Dry-run and backend smoke

# Print selected backend + step list without migrate/lint/test
REFRACT_VERIFY_DRY_RUN=1 make local-verification

# Assert unset→compose, explicit compose/native, EXEC_BACKEND override, invalid rejection
make check-local-verification-backends

Layout (scripts)

Path	Role
`scripts/shell/local-verification.sh`	Orchestrator
`scripts/shell/lib/exec-backend.sh`	Compose vs native wrappers
`scripts/shell/lib/verification-test-env.sh`	Test/codegen env + Postgres/Redis wait
`scripts/shell/lib/ensure-host-shared-schema.sh`	Native `/shared` schema copy for portal codegen
`scripts/shell/check-local-verification-backends.sh`	Dry-run case matrix

Relationship to CI

GitHub Actions (integration.yml) remains the merge gate: parallel tests (with coverage comments), builds, lints, codegen-verification, production Dockerfile / browser-static, and other jobs. make local-verification runs the same sequential checklist locally, including the codegen dirty-tree check and production browser-static smoke, so those CI jobs fail at the pre-push gate instead of only on GitHub. Coverage PR comments and parallel job speed stay in Actions. See Continuous Integration.

What’s next?

Make Commands — full target list
Continuous Integration — PR workflows
Root AGENTS.md — Cursor Cloud native verification notes

Getting Started

Architecture

Frontend

Deployment

Quality

Reference

Pipeline (same steps everywhere)

Choosing an exec backend

Native prerequisites

Dry-run and backend smoke

Layout (scripts)

Relationship to CI

What’s next?

​Pipeline (same steps everywhere)

​Choosing an exec backend

​Native prerequisites

​Dry-run and backend smoke

​Layout (scripts)

​Relationship to CI

​What’s next?

Pipeline (same steps everywhere)

Choosing an exec backend

Native prerequisites

Dry-run and backend smoke

Layout (scripts)

Relationship to CI

What’s next?