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 typecheck     # strict TypeScript
pnpm test          # Vitest
pnpm build         # Turborepo package build graph
pnpm verify        # every code gate above

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 scans modules/* without a central registry. A missing or empty modules directory is valid and reports zero installed modules.

CI runs pnpm ci:verify, which adds Compose configuration validation to pnpm verify. A separate CI job runs the live infrastructure smoke test so code-only local verification does not require Docker. The explicit 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.

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.