Ekklesia/docs/development/repository-workflow.md

Repository workflow

Prerequisites

• Node.js 24 LTS (.node-version and .nvmrc pin the reviewed patch)
• pnpm 11.12.0
• Docker with the Compose plugin for local infrastructure

Install dependencies from the committed lockfile:

pnpm install --frozen-lockfile

Quality gates

pnpm format:check  # formatting without mutation
pnpm lint          # Biome recommended rules
pnpm boundaries    # architectural directions, UI ownership, and cycles
pnpm modules:validate # installed module manifests, compatibility, and dependency graph
pnpm migrations:validate # offline module migration inventory and exact checksums
pnpm migrations:plan # read-only comparison with PostgreSQL applied history
pnpm migrations:apply # locked, transactional application of the pending batch
pnpm typecheck     # strict TypeScript
pnpm test          # Vitest
pnpm test:migrations:integration # production runner against disposable PostgreSQL
pnpm build         # Turborepo package build graph
pnpm verify        # every code-only gate; never plan or apply

The lint, typecheck, and test commands run both repository-root checks and every matching package-level Turborepo task. New packages add their own lint, typecheck, and test scripts; the root verification command discovers them automatically.

pnpm modules:validate builds the workspace, then scans modules/* without a central registry. A missing or empty modules directory is valid and reports zero installed modules. Installed modules must produce the compiled JavaScript entrypoints declared by their static manifests. Optional schema entrypoints are loaded and validated for table ownership, namespacing, duplicates, and foreign-key isolation; this command does not connect to PostgreSQL or run migrations.

pnpm migrations:validate also builds first, completes static module discovery, and atomically checks every declared stable Drizzle migration directory. It reports dependency-first module inventories and exact SHA-256 checksums without importing module code, connecting to PostgreSQL, or executing SQL. Modules with no migration history are valid.

Migration planning and application require DATABASE_URL. Keep it in the uncommitted .env created from .env.example:

cp .env.example .env
pnpm migrations:plan
pnpm migrations:apply

Planning completes discovery and validation, reads Core's applied history, and prints a deterministic applied/pending/approval-blocked inventory. It is read-only and can become stale if another process applies migrations afterward. Applying is an explicit mutating operation: it acquires the bounded Core advisory lock, rereads history, checks every destructive approval, and executes the complete pending aggregate in one transaction. A later failure rolls back all schema and history changes from that invocation; migrations committed by earlier invocations remain.

The default command composition supplies no destructive approvals. There is no --force, wildcard, or source-controlled approval escape hatch; deployments must later compose a trusted external provider that supplies an exact module ID, migration identity, and checksum triple.

Migration-runner unit tests cover orchestration through its narrow database port. Run the separate live suite when changing migration behavior:

pnpm test:migrations:integration

It requires Docker with Compose, starts the pinned PostgreSQL image with a generated throwaway credential and a Docker-assigned loopback port, creates an isolated database for each scenario, and removes its containers, network, databases, and volume afterward. It exercises the production adapter and real PostgreSQL transactions, history, advisory locks, approvals, and sanitized errors. It remains outside the Docker-free pnpm verify command.

CI runs pnpm ci:verify, which adds Compose configuration validation to pnpm verify. Separate infrastructure-smoke and migration-smoke jobs run the live service and migration suites. The exact pull-request context to add to main branch protection after merge is CI / migration-smoke (pull_request). The explicit ci:verify suffix avoids pnpm's built-in ci install command.

Development infrastructure

Create an untracked local environment file before using Compose:

cp .env.example .env
pnpm infrastructure:up

Stop services or follow their logs with:

pnpm infrastructure:down
pnpm infrastructure:logs

Exercise both services with isolated, throwaway credentials and Docker-assigned host ports:

pnpm infrastructure:smoke

The smoke test verifies PostgreSQL password authentication and authenticated S3 list, put, get, head, and delete operations. It also proves invalid database passwords, anonymous object access, and invalid S3 signatures are rejected. Its containers, network, and volumes are removed on exit. When the smoke script itself runs in a Docker-based CI job, it temporarily joins that job container to the isolated Compose network and reaches object storage by its service name. Direct host runs continue to use Docker-assigned random ports published only on loopback.

PostgreSQL and the S3 endpoint bind to 127.0.0.1 only. Compose uses persistent named volumes; infrastructure:down preserves data. The S3 service creates the configured development bucket idempotently at startup.

The checked-in credentials are safe only for local development. Deployed secrets must come from an environment-appropriate secret provider and must not be committed.

Docker is not installed in every contributor environment. Compose validation and live service health therefore run separately from the code-only pnpm verify gate.