agentic-dev/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.

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

// ✓ Correct
import type { INavigationRepository } from "../repositories/navigation.repository.interface.js";

// ✗ Wrong
import { Navigation } from "@/entities/navigation.js";

Tests use @/ alias

// ✓ Correct
import { getHeaderUseCase } from "@/application/use-cases/get-header.use-case.js";

DI container is per-feature

Tests rebind:

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

Tests

• Factories: src/__factories__/header.factory.ts and src/__factories__/nav-item.factory.ts — use headerFactory.build({ overrides }) and navItemFactory.build({ overrides }) to construct test data with stable defaults.
• Contract suite: src/__contracts__/header-repository.contract.ts — runs against every repository implementation (mock + payload).
• Unit tests: colocated as *.test.ts next to the source file.
• Feature integration: none today (no tests/ directory yet); add when a multi-layer flow needs end-to-end coverage.

pnpm test --filter @repo/navigation           # all tests for this feature
pnpm test --filter @repo/navigation -- --watch # watch mode

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

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.