Toolchain, commands, and CI

When to use: Installing dependencies, running dev/build/test/lint, filtering packages, single-test runs, git hooks, preparing a clone (.env.development / .env.test), or Docker-backed local services and dev servers.

Stack (summary)

• Runtime: Node.js 25 via mise.toml (also engines in root package.json). Use mise install / mise exec so Vitest and Uint8Array.fromHex / toHex match production; Node 22 lacks those APIs and will fail tests that touch @repo/utils crypto helpers.
• Package manager: package.json packageManager field (e.g. pnpm). Install deps: pnpm install
• Task runner: turbo via root scripts
• Lint/format: Biome (@biomejs/biome 1.9.x)
• TypeScript: 6.0.x + TypeScript 7 beta (@typescript/native-preview) for typechecking. pnpm typecheck runs tsgo (the native preview binary) — never invoke tsc directly in scripts or docs.
• Bundler: tsdown (replaces the deprecated tsup). App builds and library DTS emission run under tsdown.
• Tests: Vitest 3.x
• Core logic: Effect TS primitives
• Postgres ORM: Drizzle
• API/ingest boundaries: Hono
• Web app: TanStack Start + React

Top-level commands (repo root)

• pnpm dev — run all workspace dev tasks via Turbo
• pnpm build — run all workspace builds
• pnpm check — run all workspace lint and format check scripts
• pnpm typecheck — run all workspace typechecks
• pnpm test — run all workspace tests
• pnpm hooks — configure local git hooks for this clone

Searching the repo

grep is a shadowed shell function here, and some sources (e.g. packages/domain/spans/src/otlp/transform.ts) trip binary-file detection because of lone surrogates, which silently suppresses matches. Use command grep -a, or the dedicated search tools, before concluding a string is absent.

Git hooks (pre-commit)

• Pre-commit hook lives at .husky/pre-commit
• Pre-commit runs: pnpm check, pnpm typecheck, and pnpm knip
• Hooks are auto-configured on dependency install via root prepare script (pnpm hooks)
• Existing clones should run pnpm hooks once to configure core.hooksPath and hook permissions

Package-scoped (--filter)

pnpm --filter @app/api check
pnpm --filter @app/api typecheck
pnpm --filter @app/api build
pnpm --filter @app/api test

Path-based filtering also works:

pnpm --filter ./apps/api test
pnpm --filter ./packages/domain/workspaces check

Single-test workflows

Vitest is invoked as vitest run --passWithNoTests:

# Single test file
pnpm --filter @app/api test -- src/some-file.test.ts

# Test name pattern
pnpm --filter @app/api test -- -t "health endpoint"

# Specific file + name
pnpm --filter @app/api test -- src/some-file.test.ts -t "returns 200"

CI-equivalent local checks

Before opening PRs:

pnpm check
pnpm typecheck
pnpm test

CI workflows (check.yml, typecheck.yml, knip.yml, test.yml) use Node 25 + pnpm and run the same commands.

Cloud agent environment setup

Before starting work, ensure .env.development and .env.test exist. They are required for the dev server, tests, and tooling like knip.

cp .env.example .env.development
cp .env.example .env.test

Then set NODE_ENV appropriately:

• In .env.development: NODE_ENV=development
• In .env.test: NODE_ENV=test

This provides working defaults for all services (Postgres, ClickHouse, Redis, etc.) that match the Docker Compose setup. For LAT_* naming and parseEnv usage when you add variables, see env-configuration.

Local services (Docker) and dev apps

Start infrastructure before app processes (e.g. in cloud agents or a fresh clone):

sudo dockerd &>/dev/null &  # if the daemon is not already running
sudo docker compose up -d postgres clickhouse redis redis-bullmq mailpit temporal temporal-ui

Migrations and seeds (only when the user asked you to set up DBs in this conversation — see database-postgres and database-clickhouse-weaviate for agent rules):

pnpm --filter @platform/db-postgres pg:migrate
pnpm --filter @platform/db-clickhouse ch:up
pnpm --filter @platform/db-postgres pg:seed       # optional: seed users
pnpm --filter @platform/db-clickhouse ch:seed       # optional: sample spans

Dev servers (e.g. tmux-style):

pnpm --filter @app/web dev &
pnpm --filter @app/api dev &
pnpm --filter @app/ingest dev &
pnpm --filter @app/workers dev &
pnpm --filter @app/workflows dev &
pnpm --filter @app/design-system dev &

Service	Port	Health check
Web	3000	curl http://localhost:3000 (redirect to /login)
API	3001	curl http://localhost:3001/health
Ingest	3002	curl http://localhost:3002/health
Workers	9090	curl http://localhost:9090/health
Workflows	9091	curl http://localhost:9091/health
Design system	5173 (Vite default)	pnpm --filter @app/design-system dev
Mailpit UI	8025	curl http://localhost:8025
Temporal UI	8233	curl http://localhost:8233

Manual auth: magic links appear in Mailpit at http://localhost:8025 after signup at http://localhost:3000/signup.