Danijel Martinek
5ea4c67f93
Captures the decision to add @repo/core-testing, factories, contract suites, vitest safety defaults, coverage thresholds, Storybook test-runner, and CI as one cohesive TDD foundation. Per-feature AGENTS.md gains a Tests section pointing to factories, contract suite, and the canonical test commands. Spec: §7.4, §7.5 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
131 lines
4.3 KiB
Markdown
131 lines
4.3 KiB
Markdown
# AGENTS.md — auth
|
|
|
|
Users collection + authentication use cases (sign-in, sign-up, sign-out, password reset). Provides the Users Payload collection and tRPC procedures for authentication workflows.
|
|
|
|
## What it owns
|
|
|
|
- **Entities** — User type, auth-related errors (InvalidCredentials, UserNotFound)
|
|
- **Use cases** — Sign-in, sign-up, sign-out, verify token, reset password
|
|
- **Repository interface** — `IUsersRepository` for user persistence
|
|
- **Mock repository** — In-memory user store for tests
|
|
- **Payload repository** — Real Payload-backed user repository (constructor-injected at boot)
|
|
- **Payload collection** — Users collection definition + hooks
|
|
- **tRPC router** — Procedures for sign-in, sign-up, verify
|
|
- **DI container** — Per-feature InversifyJS container with auth symbols
|
|
- **UI components** — Auth-specific components (LoginForm, SignupForm, etc.)
|
|
|
|
## Public exports
|
|
|
|
From `package.json`:
|
|
- `.` — User type + auth errors + UI components
|
|
- `./api` — tRPC router (`authRouter`)
|
|
- `./cms` — Payload Users collection
|
|
- `./di/bind-production` — `bindProductionUsers()` to wire Payload repo at boot
|
|
|
|
## What it must NOT import
|
|
|
|
- Any other feature package (`@repo/blog`, `@repo/media`, etc.)
|
|
- Any app package
|
|
- `@repo/core-api`, `@repo/core-cms`, `@repo/core-trpc`, `@repo/core-ui` directly; only import from `@repo/core-shared` and use DI for Payload config
|
|
|
|
## Layer rules
|
|
|
|
### `src/` files use relative imports
|
|
|
|
Avoid `@/` in source code:
|
|
|
|
```typescript
|
|
// ✓ Correct
|
|
import type { IUsersRepository } from "../repositories/users.repository.interface.js";
|
|
|
|
// ✗ Wrong (don't do this in src/)
|
|
import { SomeType } from "@/entities/user.js";
|
|
```
|
|
|
|
### Tests use @/ alias
|
|
|
|
Test files use `@/`:
|
|
|
|
```typescript
|
|
// ✓ Correct
|
|
import { createUserUseCase } from "@/application/use-cases/create-user.use-case.js";
|
|
```
|
|
|
|
### DI container is per-feature
|
|
|
|
Tests rebind their own container:
|
|
|
|
```typescript
|
|
import { container as authContainer, AUTH_SYMBOLS } from "@/di/container.js";
|
|
import { MockUsersRepository } from "@/infrastructure/repositories/mock-users.repository.js";
|
|
|
|
beforeEach(() => {
|
|
authContainer.unbindAll();
|
|
authContainer.bind(AUTH_SYMBOLS.IUsersRepository).to(MockUsersRepository);
|
|
});
|
|
```
|
|
|
|
## Test conventions
|
|
|
|
- **Unit tests** colocated with source: `*.test.ts` suffix
|
|
- **Feature tests** in `tests/` folder: `*.feature.test.ts` suffix (cross-layer tests like sign-up flow)
|
|
- **Vitest environment** — `node`
|
|
- **Alias** — `@/` resolves to `src/`
|
|
- **Run** — `pnpm test --filter @repo/auth`
|
|
|
|
Covered areas: sign-in/up/out use cases, user validation, DI container binding.
|
|
|
|
## Tests
|
|
|
|
- **Factories:** `src/__factories__/user.factory.ts`, `src/__factories__/session.factory.ts` — use `userFactory.build({ overrides })` to construct test data with stable defaults.
|
|
- **Contract suite:** `src/__contracts__/users-repository.contract.ts` — runs against every repository implementation (mock + payload).
|
|
- **Unit tests:** colocated as `*.test.ts` next to the source file.
|
|
- **Feature integration:** `tests/sign-in-flow.feature.test.ts` — full slice through tRPC router → controller → use case → mock repo.
|
|
|
|
```bash
|
|
pnpm test --filter @repo/auth # all tests for this feature
|
|
pnpm test --filter @repo/auth -- --watch # watch mode
|
|
```
|
|
|
|
See `docs/guides/tdd-workflow.md` for the cycle.
|
|
|
|
## Structure (minimal feature)
|
|
|
|
```
|
|
src/
|
|
entities/
|
|
user.ts # User schema + type
|
|
errors.ts # AuthError, InvalidCredentials, etc.
|
|
application/
|
|
repositories/
|
|
users.repository.interface.ts
|
|
use-cases/
|
|
sign-in.use-case.ts
|
|
sign-up.use-case.ts
|
|
infrastructure/
|
|
repositories/
|
|
payload-users.repository.ts # constructor-injected: Config
|
|
mock-users.repository.ts
|
|
di/
|
|
symbols.ts # AUTH_SYMBOLS
|
|
container.ts # authContainer
|
|
bind-production.ts # bindProductionUsers(container, config)
|
|
interface-adapters/
|
|
controllers/
|
|
auth.controller.ts # sign-in input validation
|
|
integrations/
|
|
cms/
|
|
collections/
|
|
users.ts # Payload CollectionConfig
|
|
index.ts
|
|
api/
|
|
router.ts # tRPC procedures
|
|
index.ts
|
|
ui/
|
|
login-form.tsx
|
|
signup-form.tsx
|
|
index.ts # re-exports: User, errors, UI components
|
|
tests/
|
|
sign-up.feature.test.ts
|
|
```
|