agentic-dev/packages/auth/AGENTS.md

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.

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.

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