Danijel Martinek
ef2b8e300e
First slice of the combined Plan 8 + Plan 9 doc-update pass: - CLAUDE.md Key Conventions: append schema-in-use-case, presenter, controller unknown input, feature-scoped tRPC error mapping, public surface split (./ui) - packages/core-shared/AGENTS.md: document defineErrorMiddleware export + t re-export from trpc/init - docs/superpowers/plans/2026-05-05-plan-8-*.md and matching spec: one-line note that some controller/router patterns shifted in Plan 9; link to the Plan 9 refactor log - docs/architecture/overview.md: data-flow box now shows xProcedure + xInputSchema + xOutputSchema.parse + presenter + middleware lanes; three explanatory paragraphs added (schemas, presenter, error mapping) - docs/architecture/dependency-flow.md: app-side ./ui subpath note, allowed/disallowed examples updated for Plan 9 paths Remaining doc-pass items (root AGENTS.md, per-feature AGENTS.md ×5, core-testing AGENTS.md, adding-a-feature.md, tdd-workflow.md, testing-strategy.md, vertical-feature-spec.md) follow in subsequent commits — to be dispatched in parallel.
38 lines
2.0 KiB
Markdown
38 lines
2.0 KiB
Markdown
# AGENTS.md — core-shared
|
|
|
|
Generic, reusable primitives with **zero business knowledge**. This package is the foundation for all other packages and exports utilities, Payload field/hook definitions, and tRPC initialization.
|
|
|
|
## Responsibilities
|
|
|
|
- **Generic primitives** — environment helpers, date utilities, type guards
|
|
- **Payload utilities** — field definitions (slug, SEO), blocks (CTA), access controls (is-admin), hooks (slugify, publish timestamp)
|
|
- **tRPC platform** — `initTRPC.create()`, shared context factory, procedure builders
|
|
- **No business domain knowledge** — no awareness of articles, users, media, or any feature
|
|
|
|
## Must NOT import
|
|
|
|
- Any feature package (`@repo/auth`, `@repo/blog`, etc.)
|
|
- Any app package
|
|
- Framework-specific code (Next.js, TanStack React Query)
|
|
|
|
## Public exports
|
|
|
|
From `package.json`:
|
|
- `.` — all utilities, Payload exports, tRPC init
|
|
- `./payload` — Payload field/hook/block utilities only
|
|
- `./trpc/init` — tRPC `initTRPC` instance + builders. **Plan 9:** also exports `t` (the raw `initTRPC.create({...})` instance) so feature packages can build their own procedures via `t.procedure.use(...)`
|
|
- `./trpc/context` — tRPC context factory only
|
|
- `./trpc/define-error-middleware` — **Plan 9:** factory that builds a tRPC middleware translating domain errors to `TRPCError`. Takes `ReadonlyArray<readonly [ErrorCtor, TRPC_ERROR_CODE_KEY]>` tuples; uses `instanceof` discrimination; preserves the original error as `.cause`. **Owned by features:** each feature passes its own constructors in via `integrations/api/procedures.ts`. core-shared never enumerates feature-specific error classes — this stays boundary-clean
|
|
|
|
## Test conventions
|
|
|
|
- Tests colocated: `src/lib/slug-field.ts` → `src/lib/slug-field.test.ts`
|
|
- Vitest environment: `node`
|
|
- Alias: `@/` resolves to `src/`
|
|
- Run: `pnpm test --filter @repo/core-shared`
|
|
|
|
Covered areas:
|
|
- Slug field generation + validation
|
|
- Payload hooks (publish-at timestamp, slugify-if-missing)
|
|
- Access control helpers
|