# 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:

```bash
pnpm install --frozen-lockfile
```

## Quality gates

```bash
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 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` 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.

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:

```bash
cp .env.example .env
pnpm infrastructure:up
```

Stop services or follow their logs with:

```bash
pnpm infrastructure:down
pnpm infrastructure:logs
```

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

```bash
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.