docs(agents): per-feature + core-testing AGENTS.md for Plan 8 + Plan 9 conventions
Each per-feature AGENTS.md now reflects the post-Plan-9 layout: entity/error paths, public-API split (./ui), use-case schemas, presenter pattern, feature-scoped tRPC error map, and feature-specific errors-to-codes table. core-testing/AGENTS.md gains a Plan 9 test-patterns section documenting R25 (output validation), R26 (router error mapping), R27/R28 (presenter shape) test obligations. auth: documents real PayloadUsersRepository + AuthenticationService and the deferred session methods. media: documents the full Clean Architecture scaffold introduced in Plan 8. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -1,134 +1,137 @@
|
||||
# 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.
|
||||
Articles collection + content use cases (get articles, get article by slug, create article). Provides the Articles Payload collection and tRPC procedures for content management and retrieval.
|
||||
|
||||
## What it owns
|
||||
## Overview
|
||||
|
||||
- **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.)
|
||||
`@repo/blog` owns: Article domain model, blog-scoped errors, the `IArticlesRepository` interface, three use cases, three controllers, a real Payload-backed repository, and the tRPC `blogRouter`. Query builders live in `./ui`.
|
||||
|
||||
## Layer responsibilities
|
||||
|
||||
| Layer | Key files |
|
||||
|---|---|
|
||||
| **entities/models** | `article.ts` — Zod schema + `Article`, `ArticleStatus` types |
|
||||
| **entities/errors** | `article.ts` (ArticleNotFoundError), `common.ts` (InputParseError) |
|
||||
| **application/use-cases** | `get-articles.use-case.ts`, `create-article.use-case.ts`, `get-article-by-slug.use-case.ts` — factory functions + exported schemas |
|
||||
| **application/repositories** | `articles.repository.interface.ts` — `IArticlesRepository` |
|
||||
| **infrastructure/repositories** | `articles.repository.ts` (real Payload-backed), `articles.repository.mock.ts` (in-memory) |
|
||||
| **interface-adapters/controllers** | `get-articles.controller.ts`, `create-article.controller.ts`, `get-article-by-slug.controller.ts` — one file per use case |
|
||||
| **di** | `symbols.ts` (BLOG_SYMBOLS), `module.ts`, `container.ts`, `bind-production.ts` |
|
||||
| **integrations/api** | `procedures.ts` (blogProcedure), `router.ts` (blogRouter) |
|
||||
| **integrations/cms** | `collections/articles.ts` — Payload Articles CollectionConfig |
|
||||
| **ui** | `src/ui/index.ts` — re-exports `articleBySlugQuery` and `listArticlesQuery` |
|
||||
|
||||
## 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
|
||||
| Subpath | Contents |
|
||||
|---|---|
|
||||
| `.` | `Article`, `ArticleStatus` types; `ArticleNotFoundError`, `InputParseError`; all use-case schemas + input/output types + `IXUseCase` aliases; `IXController` type aliases; `BlogRouter` type |
|
||||
| `./ui` | `articleBySlugQuery`, `listArticlesQuery` — React Query option builders |
|
||||
| `./api` | `blogRouter` (tRPC router) |
|
||||
| `./cms` | Payload Articles collection definition |
|
||||
| `./di/bind-production` | `bindProductionBlog(container, config)` |
|
||||
|
||||
## Use-case + controller patterns
|
||||
|
||||
See `CLAUDE.md` Key Conventions and `docs/architecture/overview.md` for the canonical factory templates.
|
||||
|
||||
### Use cases
|
||||
|
||||
| Use case | Input schema | Output schema | Notes |
|
||||
|---|---|---|---|
|
||||
| `getArticlesUseCase` | `getArticlesInputSchema` — `{ status? }` (status narrowed to `articleStatusSchema`) | `getArticlesOutputSchema` — `z.array(articleSchema)` | Returns all articles (optionally filtered) |
|
||||
| `createArticleUseCase` | `createArticleInputSchema` — `{ title, slug, content, ... }` | `createArticleOutputSchema` — `articleSchema` | Creates and persists an article |
|
||||
| `getArticleBySlugUseCase` | `getArticleBySlugInputSchema` — `{ slug }` | `getArticleBySlugOutputSchema` — `articleSchema` | Throws `ArticleNotFoundError` when slug not found |
|
||||
|
||||
### Controllers
|
||||
|
||||
All three controllers use identity presenters — `function presenter(value: XOutput) { return value; }` — and return `Promise<ReturnType<typeof presenter>>`. All accept `unknown` input and `safeParse` with the use-case's `xInputSchema`, throwing `InputParseError` on failure.
|
||||
|
||||
## Errors → tRPC codes
|
||||
|
||||
| Error class | tRPC code | Thrown by |
|
||||
|---|---|---|
|
||||
| `InputParseError` | `BAD_REQUEST` | controllers (safeParse failure) |
|
||||
| `ArticleNotFoundError` | `NOT_FOUND` | `getArticleBySlugUseCase` |
|
||||
|
||||
Defined in `src/integrations/api/procedures.ts` via `blogProcedure = t.procedure.use(defineErrorMiddleware([...]))`.
|
||||
|
||||
## Tests
|
||||
|
||||
- **Factories:** `src/__factories__/article.factory.ts`
|
||||
- **Contract suite:** `src/__contracts__/articles-repository.contract.ts` — runs against mock and real `ArticlesRepository`
|
||||
- **Unit tests:** colocated `*.test.ts` next to each source file
|
||||
- **Feature integration:** `tests/articles.feature.test.ts` — full slice: tRPC caller → controller → use case → mock repo
|
||||
- **R25** (output validation): each of the three use-case test files has a test that injects a malformed repository mock and asserts `.rejects.toBeInstanceOf(ZodError)`.
|
||||
- **R26** (router error mapping): `router.test.ts` has `NOT_FOUND` on `articleBySlug` with unknown slug, and `BAD_REQUEST` on empty input.
|
||||
- **R27/R28** (presenter shape): all three controllers use identity presenters — no reshape test obligation; the returned value equals the use-case output.
|
||||
|
||||
```bash
|
||||
pnpm test --filter @repo/blog
|
||||
pnpm test --filter @repo/blog -- --watch
|
||||
```
|
||||
|
||||
See `docs/guides/tdd-workflow.md` for the full cycle.
|
||||
|
||||
## Directory structure
|
||||
|
||||
```
|
||||
src/
|
||||
entities/
|
||||
models/
|
||||
article.ts
|
||||
errors/
|
||||
article.ts # ArticleNotFoundError
|
||||
common.ts # InputParseError
|
||||
application/
|
||||
repositories/
|
||||
articles.repository.interface.ts
|
||||
use-cases/
|
||||
get-articles.use-case.ts
|
||||
create-article.use-case.ts
|
||||
get-article-by-slug.use-case.ts
|
||||
infrastructure/
|
||||
repositories/
|
||||
articles.repository.ts # real Payload-backed
|
||||
articles.repository.mock.ts
|
||||
interface-adapters/
|
||||
controllers/
|
||||
get-articles.controller.ts
|
||||
create-article.controller.ts
|
||||
get-article-by-slug.controller.ts
|
||||
integrations/
|
||||
api/
|
||||
procedures.ts # blogProcedure
|
||||
router.ts # blogRouter
|
||||
cms/
|
||||
collections/
|
||||
articles.ts
|
||||
index.ts
|
||||
di/
|
||||
symbols.ts # BLOG_SYMBOLS
|
||||
module.ts
|
||||
container.ts
|
||||
bind-production.ts
|
||||
ui/
|
||||
index.ts # articleBySlugQuery, listArticlesQuery
|
||||
query.ts
|
||||
index.ts
|
||||
__factories__/
|
||||
article.factory.ts
|
||||
__contracts__/
|
||||
articles-repository.contract.ts
|
||||
tests/
|
||||
articles.feature.test.ts
|
||||
```
|
||||
|
||||
## 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
|
||||
- `@repo/core-api`, `@repo/core-cms`, `@repo/core-trpc`, `@repo/core-ui` directly; only `@repo/core-shared`
|
||||
|
||||
## Layer rules
|
||||
## Cross-links
|
||||
|
||||
### `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.
|
||||
|
||||
## Tests
|
||||
|
||||
- **Factories:** `src/__factories__/article.factory.ts` — use `articleFactory.build({ overrides })` to construct test data with stable defaults.
|
||||
- **Contract suite:** `src/__contracts__/articles-repository.contract.ts` — runs against every repository implementation (mock + payload).
|
||||
- **Unit tests:** colocated as `*.test.ts` next to the source file.
|
||||
- **Feature integration:** `tests/articles.feature.test.ts` — full slice through tRPC router → controller → use case → mock repo.
|
||||
|
||||
```bash
|
||||
pnpm test --filter @repo/blog # all tests for this feature
|
||||
pnpm test --filter @repo/blog -- --watch # watch mode
|
||||
```
|
||||
|
||||
See `docs/guides/tdd-workflow.md` for the cycle.
|
||||
|
||||
## 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
|
||||
```
|
||||
- ADR-012 (`docs/decisions/adr-012-lazar-conformance.md`) — factory-style use cases, per-use-case controllers, file-naming conventions
|
||||
- ADR-013 (`docs/decisions/adr-013-input-output-unification.md`) — schemas-in-use-case, presenter, `./ui` subpath, error middleware
|
||||
- Refactor logs: `docs/superpowers/refactor-logs/2026-05-05-lazar-pattern-conformance.md` (Plan 8), `docs/superpowers/refactor-logs/2026-05-06-input-output-unification.md` (Plan 9)
|
||||
|
||||
Reference in New Issue
Block a user