diff --git a/packages/auth/AGENTS.md b/packages/auth/AGENTS.md new file mode 100644 index 0000000..f90835c --- /dev/null +++ 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 +``` diff --git a/packages/blog/AGENTS.md b/packages/blog/AGENTS.md new file mode 100644 index 0000000..3739177 --- /dev/null +++ b/packages/blog/AGENTS.md @@ -0,0 +1,120 @@ +# AGENTS.md — blog + +Articles collection + content use cases (get article, list articles, create, publish, unpublish). Provides the Articles Payload collection and tRPC procedures for content management and retrieval. + +## What it owns + +- **Entities** — Article type, article-related errors (ArticleNotFound, InvalidSlug) +- **Use cases** — Get article, list articles, create, publish, unpublish, delete +- **Repository interface** — `IArticlesRepository` for article persistence +- **Mock repository** — In-memory article store for tests +- **Payload repository** — Real Payload-backed article repository (constructor-injected at boot) +- **Payload collection** — Articles collection definition + hooks (publish timestamp, slugify) +- **tRPC router** — Procedures for list, get-by-slug, create, publish +- **DI container** — Per-feature InversifyJS container with blog symbols +- **UI components** — Article-specific components (ArticleCard, ArticleList, etc.) + +## Public exports + +From `package.json`: +- `.` — Article type + blog errors + UI components +- `./api` — tRPC router (`blogRouter`) +- `./cms` — Payload Articles collection +- `./di/bind-production` — `bindProductionArticles()` to wire Payload repo at boot + +## What it must NOT import + +- Any other feature package (`@repo/auth`, `@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 { IArticlesRepository } from "../repositories/articles.repository.interface.js"; + +// ✗ Wrong (don't do this in src/) +import { Article } from "@/entities/article.js"; +``` + +### Tests use @/ alias + +Test files use `@/`: + +```typescript +// ✓ Correct +import { getArticleUseCase } from "@/application/use-cases/get-article.use-case.js"; +``` + +### DI container is per-feature + +Tests rebind their own container: + +```typescript +import { container as blogContainer, BLOG_SYMBOLS } from "@/di/container.js"; +import { MockArticlesRepository } from "@/infrastructure/repositories/mock-articles.repository.js"; + +beforeEach(() => { + blogContainer.unbindAll(); + blogContainer.bind(BLOG_SYMBOLS.IArticlesRepository).to(MockArticlesRepository); +}); +``` + +## Test conventions + +- **Unit tests** colocated with source: `*.test.ts` suffix +- **Feature tests** in `tests/` folder: `*.feature.test.ts` suffix (cross-layer tests like publish flow) +- **Vitest environment** — `node` +- **Alias** — `@/` resolves to `src/` +- **Run** — `pnpm test --filter @repo/blog` + +Covered areas: article CRUD use cases, slug validation, publish/unpublish flows, DI container binding. + +## Structure + +``` +src/ + entities/ + article.ts # Article schema + type + errors.ts # ArticleNotFound, InvalidSlug, etc. + application/ + repositories/ + articles.repository.interface.ts + use-cases/ + get-article.use-case.ts + list-articles.use-case.ts + publish-article.use-case.ts + infrastructure/ + repositories/ + payload-articles.repository.ts # constructor-injected: Config + mock-articles.repository.ts + di/ + symbols.ts # BLOG_SYMBOLS + container.ts # blogContainer + bind-production.ts # bindProductionArticles(container, config) + interface-adapters/ + controllers/ + articles.controller.ts # input validation + integrations/ + cms/ + collections/ + articles.ts # Payload CollectionConfig + hooks/ + after-publish.ts # revalidate, effects + index.ts + api/ + router.ts # tRPC procedures + index.ts + ui/ + article-card.tsx + article-list.tsx + query.ts # typed tRPC query helpers + index.ts # re-exports: Article, UI components +tests/ + publish-article.feature.test.ts +``` diff --git a/packages/marketing-pages/AGENTS.md b/packages/marketing-pages/AGENTS.md new file mode 100644 index 0000000..2cd58f9 --- /dev/null +++ b/packages/marketing-pages/AGENTS.md @@ -0,0 +1,119 @@ +# AGENTS.md — marketing-pages + +Pages collection and SiteSettings global for site-wide metadata. Provides marketing/landing page content, SEO settings, and site configuration via Payload. + +## What it owns + +- **Entities** — Page type (slug, title, content, published), SiteSettings type (site name, description, logo) +- **Use cases** — Get page, list pages, publish page, get site settings, update settings +- **Repository interfaces** — `IPagesRepository`, `ISiteSettingsRepository` +- **Mock repositories** — In-memory stores for tests +- **Payload repositories** — Real Payload-backed repositories (constructor-injected at boot) +- **Payload collection** — Pages collection definition +- **Payload global** — SiteSettings global definition +- **tRPC router** — Procedures for list pages, get page, get site settings +- **DI container** — Per-feature InversifyJS container with marketing-pages symbols +- **UI components** — Page display, hero section, CTA blocks, footer with site settings + +## Public exports + +From `package.json`: +- `.` — Page type, SiteSettings type, UI components +- `./api` — tRPC router (`marketingPagesRouter`) +- `./cms` — Payload Pages collection + SiteSettings global (as separate exports) +- `./di/bind-production` — `bindProductionMarketing()` to wire Payload repos at boot + +## What it must NOT import + +- Any other feature package (`@repo/auth`, `@repo/blog`, 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 + +```typescript +// ✓ Correct +import type { IPagesRepository } from "../repositories/pages.repository.interface.js"; + +// ✗ Wrong +import { Page } from "@/entities/page.js"; +``` + +### Tests use @/ alias + +```typescript +// ✓ Correct +import { getPageUseCase } from "@/application/use-cases/get-page.use-case.js"; +``` + +### DI container is per-feature + +Tests rebind: + +```typescript +import { container as marketingContainer, MARKETING_SYMBOLS } from "@/di/container.js"; +import { MockPagesRepository } from "@/infrastructure/repositories/mock-pages.repository.js"; + +beforeEach(() => { + marketingContainer.unbindAll(); + marketingContainer.bind(MARKETING_SYMBOLS.IPagesRepository).to(MockPagesRepository); +}); +``` + +## Test conventions + +- **Unit tests** colocated: `*.test.ts` +- **Feature tests** in `tests/`: `*.feature.test.ts` +- **Vitest environment** — `node` +- **Alias** — `@/` resolves to `src/` +- **Run** — `pnpm test --filter @repo/marketing-pages` + +## Structure (minimal) + +``` +src/ + entities/ + page.ts + site-settings.ts + errors.ts + application/ + repositories/ + pages.repository.interface.ts + site-settings.repository.interface.ts + use-cases/ + get-page.use-case.ts + list-pages.use-case.ts + get-site-settings.use-case.ts + infrastructure/ + repositories/ + payload-pages.repository.ts + payload-site-settings.repository.ts + mock-pages.repository.ts + mock-site-settings.repository.ts + di/ + symbols.ts + container.ts + bind-production.ts + interface-adapters/ + controllers/ + pages.controller.ts + integrations/ + cms/ + collections/ + pages.ts + globals/ + site-settings.ts + index.ts + api/ + router.ts + index.ts + ui/ + page-display.tsx + hero-section.tsx + footer.tsx + index.ts +tests/ + publish-page.feature.test.ts +``` diff --git a/packages/media/AGENTS.md b/packages/media/AGENTS.md new file mode 100644 index 0000000..4c47c3c --- /dev/null +++ b/packages/media/AGENTS.md @@ -0,0 +1,109 @@ +# AGENTS.md — media + +Media collection for uploads (images, PDFs, etc.) and media-related use cases (upload, delete, list). Provides the Media Payload collection and tRPC procedures for asset management. + +## What it owns + +- **Entities** — Media type (filename, mimetype, size, URL), upload errors +- **Use cases** — Upload media, delete media, list media, get media +- **Repository interface** — `IMediaRepository` for media persistence +- **Mock repository** — In-memory media store for tests +- **Payload repository** — Real Payload-backed media repository (constructor-injected at boot) +- **Payload collection** — Media collection definition +- **tRPC router** — Procedures for upload, delete, list +- **DI container** — Per-feature InversifyJS container with media symbols +- **UI components** — Media upload form, media gallery + +## Public exports + +From `package.json`: +- `.` — Media type + media errors + UI components +- `./api` — tRPC router (`mediaRouter`) +- `./cms` — Payload Media collection +- `./di/bind-production` — `bindProductionMedia()` to wire Payload repo at boot + +## What it must NOT import + +- Any other feature package (`@repo/auth`, `@repo/blog`, 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 + +```typescript +// ✓ Correct +import type { IMediaRepository } from "../repositories/media.repository.interface.js"; + +// ✗ Wrong +import { Media } from "@/entities/media.js"; +``` + +### Tests use @/ alias + +```typescript +// ✓ Correct +import { uploadMediaUseCase } from "@/application/use-cases/upload-media.use-case.js"; +``` + +### DI container is per-feature + +Tests rebind their own container: + +```typescript +import { container as mediaContainer, MEDIA_SYMBOLS } from "@/di/container.js"; +import { MockMediaRepository } from "@/infrastructure/repositories/mock-media.repository.js"; + +beforeEach(() => { + mediaContainer.unbindAll(); + mediaContainer.bind(MEDIA_SYMBOLS.IMediaRepository).to(MockMediaRepository); +}); +``` + +## Test conventions + +- **Unit tests** colocated: `*.test.ts` +- **Feature tests** in `tests/`: `*.feature.test.ts` +- **Vitest environment** — `node` +- **Alias** — `@/` resolves to `src/` +- **Run** — `pnpm test --filter @repo/media` + +## Structure (minimal) + +``` +src/ + entities/ + media.ts # Media schema + type + errors.ts # UploadError, InvalidMimetype, etc. + application/ + repositories/ + media.repository.interface.ts + use-cases/ + upload-media.use-case.ts + delete-media.use-case.ts + infrastructure/ + repositories/ + payload-media.repository.ts + mock-media.repository.ts + di/ + symbols.ts + container.ts + bind-production.ts + interface-adapters/ + controllers/ + media.controller.ts + integrations/ + cms/ + collections/ + media.ts + index.ts + api/ + router.ts + index.ts + ui/ + upload-form.tsx + index.ts +tests/ + upload.feature.test.ts +``` diff --git a/packages/navigation/AGENTS.md b/packages/navigation/AGENTS.md new file mode 100644 index 0000000..baaa3ae --- /dev/null +++ b/packages/navigation/AGENTS.md @@ -0,0 +1,112 @@ +# AGENTS.md — navigation + +Header global for main site navigation. Provides the Header Payload global and tRPC procedures for dynamic navigation content. + +## What it owns + +- **Entities** — Navigation type (title, links, menu items) +- **Use cases** — Get header, update header +- **Repository interface** — `INavigationRepository` for navigation persistence +- **Mock repository** — In-memory navigation store for tests +- **Payload repository** — Real Payload-backed navigation repository (constructor-injected at boot) +- **Payload global** — Header global definition +- **tRPC router** — Procedures for get header +- **DI container** — Per-feature InversifyJS container with navigation symbols +- **UI components** — Navigation menu, header with branding + +## Public exports + +From `package.json`: +- `.` — Navigation type + UI components (NavigationMenu, Header) +- `./api` — tRPC router (`navigationRouter`) +- `./cms` — Payload Header global +- `./di/bind-production` — `bindProductionNavigation()` to wire Payload repo at boot + +## What it must NOT import + +- Any other feature package (`@repo/auth`, `@repo/blog`, 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 + +```typescript +// ✓ Correct +import type { INavigationRepository } from "../repositories/navigation.repository.interface.js"; + +// ✗ Wrong +import { Navigation } from "@/entities/navigation.js"; +``` + +### Tests use @/ alias + +```typescript +// ✓ Correct +import { getHeaderUseCase } from "@/application/use-cases/get-header.use-case.js"; +``` + +### DI container is per-feature + +Tests rebind: + +```typescript +import { container as navContainer, NAV_SYMBOLS } from "@/di/container.js"; +import { MockNavigationRepository } from "@/infrastructure/repositories/mock-navigation.repository.js"; + +beforeEach(() => { + navContainer.unbindAll(); + navContainer.bind(NAV_SYMBOLS.INavigationRepository).to(MockNavigationRepository); +}); +``` + +## Test conventions + +- **Unit tests** colocated: `*.test.ts` +- **Feature tests** in `tests/`: `*.feature.test.ts` +- **Vitest environment** — `node` +- **Alias** — `@/` resolves to `src/` +- **Run** — `pnpm test --filter @repo/navigation` + +## Structure (minimal) + +Per spec addendum v5 ("create folders only when needed"), this feature is small: + +``` +src/ + entities/ + navigation.ts # Navigation/Header schema + application/ + repositories/ + navigation.repository.interface.ts + use-cases/ + get-header.use-case.ts + infrastructure/ + repositories/ + payload-navigation.repository.ts + mock-navigation.repository.ts + di/ + symbols.ts + container.ts + bind-production.ts + interface-adapters/ + controllers/ + navigation.controller.ts + integrations/ + cms/ + globals/ + header.ts # Payload GlobalConfig + index.ts + api/ + router.ts + index.ts + ui/ + navigation-menu.tsx + header.tsx + index.ts +tests/ + get-header.feature.test.ts +``` + +No `application/use-cases/` subdirectory; just one or two use-cases at the top level.