toolchain-commands

# 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`) ```bash 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: ```bash pnpm --filter ./apps/api test pnpm --filter ./packages/domain/workspaces check ``` ## Single-test workflows Vitest is invoked as `vitest run --passWithNoTests`: ```bash # 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: ```bash 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`. ```bash 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](../env-configuration/SKILL.md). ## Local services (Docker) and dev apps Start infrastructure before app processes (e.g. in cloud agents or a fresh clone): ```bash 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](../database-postgres/SKILL.md) and [database-clickhouse-weaviate](../database-clickhouse-weaviate/SKILL.md) for agent rules): ```bash 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): ```bash 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`.