Skip to main content
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)

  1. migrate-up
  2. build-lint-deps (shared + tooling-eslint-refract)
  3. lint-all
  4. build-all
  5. test-all
  6. gql-codegen
  7. gql-codegen-dirty-tree (fail if generated files are uncommitted — same check as CI codegen-verification)
  8. verify-production-smoke (Railway Dockerfile.production build + throwaway Postgres/Redis + migrate/seed from the image + health/CSP — same as CI production-smoke)
Step order differs by backend:

Choosing an exec backend

Set via environment or Make override:
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:
  • Docker for verify-production-smoke (production image build, throwaway Postgres/Redis, Railway migrate+seed, health + CSP). Locally the step warns and skips if Docker is missing; CI fails hard. Chrome/Chromium is required for the CSP browser check (same skip-vs-fail split).
  • 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:
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

Layout (scripts)

Relationship to CI

GitHub Actions (integration.yml) remains the merge gate: parallel tests (with coverage comments), builds, lints, codegen-verification, production-smoke, and other jobs. make local-verification runs the same sequential checklist locally, including the codegen dirty-tree check and production 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?