docs(agents): add per-package AGENTS.md for all feature packages

2026-05-05 09:58:42 +02:00
parent 956b38fb00
commit 440315a4c1
5 changed files with 576 additions and 0 deletions
--- a/packages/auth/AGENTS.md
+++ b/packages/auth/AGENTS.md
@@ -0,0 +1,116 @@
+# 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.
+
+## 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
+```