diff --git a/AGENTS.md b/AGENTS.md index 5dc0738..c5cb9d0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -72,13 +72,16 @@ No other cross-package boundary deviations are permitted. ## Adding a Feature -Start with `docs/guides/adding-a-feature.md` for a step-by-step walkthrough covering: -- New feature scaffold (folder structure, `package.json`, `tsconfig.json`, `vitest.config.ts`) -- Clean Architecture layers (entities, use cases, repositories, DI container, controllers) -- Payload integration (collections, hooks, Payload repository binding) -- tRPC integration (routers, procedure binding) -- Core wiring (`core-api`, `core-cms`, path aliases, app bootstrap) -- Testing and lint validation +**Fast path — use the generator.** `pnpm turbo gen feature` scaffolds a Lazar-conformant package under `packages//` (single entity, single `getX` use case) matching the `navigation` reference shape. It emits package files, entities, use case + controller (with input/output schemas + presenter), mock + real repositories (real one is a Phase-1 stub), DI container, both binders (`bind-production` / `bind-dev-seed`), tRPC procedures + router with tests, contract suite, dev seed, and an empty `ui/` barrel — all wired with the span + capture sandwich at bind time. + +```bash +pnpm turbo gen feature # interactive +pnpm turbo gen feature --args widgets Widget widgets # non-interactive: +``` + +The generator does NOT wire aggregators or emit Payload CMS templates / faker factories / multi-entity layouts. After running, hand-edit `apps/web-next/src/server/bind-production.ts`, `packages/core-api/src/root.ts`, and the two `package.json` files (the generator prints the exact checklist on success). See `docs/guides/scaffolding-a-feature.md` for the full reference. + +**Manual path.** When the generator's Phase-1 scope doesn't fit (multiple entities/use cases, custom layout, extending an existing feature), follow `docs/guides/adding-a-feature.md` — a step-by-step walkthrough covering folder structure, Clean Architecture layers, Payload + tRPC integration, core wiring, and testing / lint validation. --- @@ -90,6 +93,7 @@ pnpm dev # Start all dev servers (Next.js :3000, CMS :3001, Storyb pnpm typecheck # Type-check all packages pnpm lint # Lint all packages (ESLint boundaries enforced) pnpm turbo boundaries # Validate workspace dependency graph (Turbo boundaries) +pnpm turbo gen feature # Scaffold a new Lazar-conformant feature package (see docs/guides/scaffolding-a-feature.md) pnpm test # Run all unit + integration tests (Vitest) pnpm test:e2e # Run e2e tests (Playwright across both apps) pnpm build # Build all packages (Turborepo) @@ -440,7 +444,8 @@ Feature packages MUST NOT `import "@sentry/*"`. Allowlist: - **Vertical Feature Spec** — `docs/architecture/vertical-feature-spec.md` — full design, rationale, decision log - **Architecture Overview** — `docs/architecture/overview.md` — package responsibilities, data flow - **Dependency Flow** — `docs/architecture/dependency-flow.md` — allowed directions and composition pattern -- **Adding a Feature Guide** — `docs/guides/adding-a-feature.md` — step-by-step new feature walkthrough +- **Scaffolding a Feature** — `docs/guides/scaffolding-a-feature.md` — `turbo gen feature` reference (fast path) +- **Adding a Feature Guide** — `docs/guides/adding-a-feature.md` — step-by-step new feature walkthrough (manual path) - **Testing Strategy** — `docs/guides/testing-strategy.md` — test placement, Vitest per-package, Playwright e2e - **TDD Workflow** — `docs/guides/tdd-workflow.md` — red-green-refactor cycle, mocking decision tree, coverage targets diff --git a/CLAUDE.md b/CLAUDE.md index 9d781d5..be0f32d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -3,12 +3,13 @@ ## Quick Start ```bash -pnpm install # Install all dependencies -pnpm dev # Start all dev servers -pnpm build # Build all packages -pnpm test # Run all tests -pnpm turbo boundaries # Validate workspace dependency graph -docker compose up -d # Start PostgreSQL +pnpm install # Install all dependencies +pnpm dev # Start all dev servers +pnpm build # Build all packages +pnpm test # Run all tests +pnpm turbo boundaries # Validate workspace dependency graph +pnpm turbo gen feature # Scaffold a new feature package (see docs/guides/scaffolding-a-feature.md) +docker compose up -d # Start PostgreSQL ``` ## TDD @@ -31,7 +32,8 @@ Turborepo + pnpm monorepo organized by vertical features. Each feature (`auth`, - `AGENTS.md` — Package map, boundary rules, per-package conventions - `docs/architecture/overview.md` — High-level architecture and package responsibilities - `docs/architecture/vertical-feature-spec.md` — Design spec with rationale and decision log -- `docs/guides/adding-a-feature.md` — End-to-end new feature walkthrough +- `docs/guides/scaffolding-a-feature.md` — `turbo gen feature` reference (fast path; prefer this over the manual walkthrough) +- `docs/guides/adding-a-feature.md` — End-to-end new feature walkthrough (manual path; for cases the generator's Phase-1 scope doesn't cover) ## Key Conventions diff --git a/docs/guides/adding-a-feature.md b/docs/guides/adding-a-feature.md index 7c67e44..07be271 100644 --- a/docs/guides/adding-a-feature.md +++ b/docs/guides/adding-a-feature.md @@ -4,6 +4,15 @@ A feature is a vertical slice: domain entities, use cases, repositories, tRPC router, CMS collection, DI container, and query builders — all owned by one package under `packages//`. +> **Prefer the generator.** `pnpm turbo gen feature` produces a +> Lazar-conformant single-entity / single-use-case package matching the +> `navigation` reference shape (DI, tRPC router with tests, span + capture +> sandwich, dev seed, contract suite). See +> [Scaffolding a Feature](./scaffolding-a-feature.md). Use this guide when +> the generator's Phase-1 scope doesn't fit — multi-entity layouts, custom +> shapes, or extending an existing feature — or when you need to understand +> what the generator emits and why. + **New feature or extension?** A new capability gets a new package (e.g., `packages/comments`). Adding an operation to an existing feature (e.g., a `publishArticle` procedure to `packages/blog`) means extending that