agentic-dev-template/packages/navigation/AGENTS.md

AGENTS.md — navigation

Header global for main site navigation. Provides the Header Payload global and tRPC procedures for dynamic navigation content.

Overview

@repo/navigation owns: Header and HeaderItem domain models, navigation-scoped errors, the IHeaderRepository interface, one use case, one controller, a real Payload-backed repository, and the tRPC navigationRouter. The headerQuery React Query builder lives in ./ui.

Layer responsibilities

Layer	Key files
entities/models	header.ts — Header, HeaderItem Zod schemas + types
entities/errors	header.ts (HeaderNotFoundError), common.ts (InputParseError)
application/use-cases	get-header.use-case.ts — factory function + exported schemas
application/repositories	header.repository.interface.ts — IHeaderRepository
infrastructure/repositories	header.repository.ts (real Payload-backed), header.repository.mock.ts (in-memory)
interface-adapters/controllers	get-header.controller.ts — one file per use case
di	symbols.ts (NAVIGATION_SYMBOLS), module.ts, container.ts, bind-production.ts
integrations/api	procedures.ts (navigationProcedure), router.ts (navigationRouter)
integrations/cms	globals/header.ts — Payload Header GlobalConfig
ui	src/ui/index.ts — re-exports headerQuery

Public exports

Subpath	Contents
.	Header, HeaderItem types; HeaderNotFoundError, InputParseError; getHeaderInputSchema, getHeaderOutputSchema, GetHeaderInput, GetHeaderOutput, IGetHeaderUseCase; IGetHeaderController type alias; NavigationRouter type
./ui	headerQuery — React Query option builder
./api	navigationRouter (tRPC router)
./cms	Payload Header global definition
./di/bind-production	bindProductionNavigation(ctx: BindProductionContext) — swaps mock impls for real Payload-backed ones at app boot
./di/bind-dev-seed	bindDevSeedNavigation(ctx: BindContext) — replaces the default empty mock with a populated one for dev / Storybook

Use-case + controller patterns

See CLAUDE.md Key Conventions and docs/architecture/overview.md for the canonical factory templates.

Use case

Use case	Input schema	Output schema	Notes
getHeaderUseCase	getHeaderInputSchema — z.object({}).strict() (void input)	getHeaderOutputSchema — = headerSchema	Takes _input: GetHeaderInput; throws HeaderNotFoundError when repository returns falsy; ends with getHeaderOutputSchema.parse(header)

Controller

getHeaderController uses an identity presenter — function presenter(value: GetHeaderOutput) { return value; } — and returns Promise<ReturnType<typeof presenter>>. Accepts unknown input and safeParse with getHeaderInputSchema, throwing InputParseError on failure.

Errors → tRPC codes

Error class	tRPC code	Thrown by
InputParseError	BAD_REQUEST	controller (safeParse failure; also triggers on strict() rejecting unknown keys)
HeaderNotFoundError	NOT_FOUND	getHeaderUseCase when repository returns falsy

Defined in src/integrations/api/procedures.ts via navigationProcedure = t.procedure.use(defineErrorMiddleware([...])).

Tests

• Factories: src/__factories__/header.factory.ts, src/__factories__/nav-item.factory.ts
• Contract suite: src/__contracts__/header-repository.contract.ts — runs against mock and real HeaderRepository
• Unit tests: colocated *.test.ts next to each source file
• R25 (output validation): get-header.use-case.test.ts has a test using an inline malformed repository mock (e.g., { items: [{ label: "", href: "/", external: false }] }, label failing min(1)) to assert .rejects.toBeInstanceOf(ZodError).
• R26 (router error mapping): router.test.ts asserts BAD_REQUEST when input has extra unknown keys (strict mode rejection → InputParseError), and NOT_FOUND via an inline NullHeaderRepository rebind causing HeaderNotFoundError.

pnpm test --filter @repo/navigation
pnpm test --filter @repo/navigation -- --watch

See docs/guides/tdd-workflow.md for the full cycle.

Directory structure

src/
  entities/
    models/
      header.ts        # Header, HeaderItem schemas + types
    errors/
      header.ts        # HeaderNotFoundError
      common.ts        # InputParseError
  application/
    repositories/
      header.repository.interface.ts
    use-cases/
      get-header.use-case.ts
  infrastructure/
    repositories/
      header.repository.ts          # real Payload-backed
      header.repository.mock.ts
  interface-adapters/
    controllers/
      get-header.controller.ts
  integrations/
    api/
      procedures.ts    # navigationProcedure
      router.ts        # navigationRouter
    cms/
      globals/
        header.ts
      index.ts
  di/
    symbols.ts
    module.ts
    container.ts
    bind-production.ts
  ui/
    index.ts           # headerQuery
    query.ts
  index.ts
  __factories__/
    header.factory.ts
    nav-item.factory.ts
  __contracts__/
    header-repository.contract.ts

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 @repo/core-shared

  Note: @repo/core-trpc and @repo/core-ui are optional packages scaffolded via pnpm turbo gen core-package trpc / ui. If not present, these constraints still apply to any future installation.

Cross-links

• ADR-012 (docs/decisions/adr-012-feature-conventions.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