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