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:

// ✓ 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 @/:

// ✓ Correct
import { createUserUseCase } from "@/application/use-cases/create-user.use-case.js";

DI container is per-feature

Tests rebind their own container:

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.

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

3.6 KiB Raw Blame History