124 lines
5.6 KiB
Markdown
124 lines
5.6 KiB
Markdown
# 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 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`:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```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.
|