Dev environment

Pinned tools with mise

Tool versions are pinned in mise.toml at the repo root — node (LTS), bun, kubectl, helm, helmfile, kubeconform, sops, age, and rust. Install mise and let it provision the pinned versions, then bootstrap dependencies:

mise install          # provision pinned tool versions
bun install           # install workspace dependencies (also: `mise run bootstrap`)

mise.toml also defines convenience tasks (mise run dev, mise run lint, mise run typecheck, mise run test, mise run helm-diff, …) that wrap the corresponding bun run scripts.

Environment variables

Shell/deploy configuration is layered through vars.sh, which sources a gitignored vars.local.sh for per-machine overrides (kube context, cluster domain, namespaces, and similar). App-level runtime config uses .env* files; .env.local and .env.*.local are gitignored. Never commit secrets — secret material lives under infra/secrets/ behind sops/age.

Everyday scripts

Scripts are check-default: a bare verb never mutates.

• bun run typecheck — turbo-run per-package type checks (never call tsc directly).
• bun run lint / bun run format — oxlint / oxfmt in check mode.
• bun run fix — the mutating pair: format:write then lint:fix.
• bun run test — unit tests (turbo).
• bun run dev — run the active dev tasks via turbo (or target one app: dev:learner, dev:teacher, dev:admin, dev:ui).

Validation gate

bun run validate is the pre-commit gate (installed via prepare → hooks:install, which points core.hooksPath at .githooks/). It runs the i18n and terminology guards, then format/lint/typecheck and coverage over the affected graph. bun run validate:full runs the same unscoped, plus chart hygiene — the shape CI enforces. The pre-commit hook always runs; it is never bypassed with --no-verify.

Test lanes

• Unit — bun run test (and test:coverage), turbo-orchestrated per package.
• Integration — bun run test:integration runs the container-backed lanes against real PostgreSQL/Electric via isolated podman-compose projects (specs under infra/compose/), torn down after each run. These are never in the commit path; they run in the PR/main gates.
• Conformance & e2e — dedicated scripts under tools/scripts/ (test:qti:conformance, test:cmi5:conformance, test:e2e, …) drive the standards conformance and Playwright suites.

See the runbooks for operational procedures (migrations, conformance suites, key management) and regenerate-migrations for the migration workflow specifically.