dev-booster 1.17.2 → 1.18.1

package/template/.devbooster/hub/knowledge/index.md

@@ -0,0 +1,91 @@
+# 📚 Dev Booster — Knowledge Base
+
+> Consolidated knowledge base for Dev Booster.
+> Each article documents a problem pattern + validated solution.
+
+---
+
+## How to Use
+
+1. Identify the concrete technical decision or problem pattern (e.g., framework behavior, migration concern, ESLint rule name, error message, or symptom).
+2. Check the index below to locate the relevant article and section.
+3. Use `read_file` with `start_line`/`end_line` to read **only** the necessary local section.
+4. **Always read the official source linked by that section before choosing or applying a solution.** Use the local entry for field-validated context and the official source for current API, version, constraints, and migration guidance.
+5. Inspect the actual project: installed versions, local rules, existing abstractions, configuration, conventions, and relevant tests.
+6. Preserve a valid established project convention. Do not replace it only because another official approach is also valid; recommend a change only when the developer requests it or evidence shows the current approach is incompatible, unsafe, deprecated, broken, or responsible for a verified issue.
+
+### Example
+
+User reports: `TS2345: Type 'string' is not assignable to type 'number'`
+
+1. Identify the pattern → TypeScript strict error on a discriminated union or runtime type mismatch.
+2. Check the index → `typescript-patterns.md` table entry confirms it covers "null safety, discriminated UI states, runtime validation".
+3. Read the relevant section → `read_file` with `start_line`/`end_line` to get only the "null-safety" section of `typescript-patterns.md`.
+4. Read the official source → open the [TypeScript Handbook section on Narrowing](https://www.typescriptlang.org/docs/handbook/2/narrowing.html) to verify current API behavior.
+5. Inspect the project → check `tsconfig.json` strict flags, existing type guards in the codebase, and whether the error is in a new area or a pre-typed module.
+6. Decide → if the project already uses a consistent pattern (e.g. Zod schemas + inferred types), preserve it. Only suggest a different approach if the current one is incompatible, unsafe, or the user explicitly requests a change.
+
+---
+
+### If Not Found in the Base
+
+Use the relevant **official source** below. Prefer primary documentation, official changelogs, and official migration guides over blog posts, search snippets, or unverified answers.
+
+| Area | Trusted sources |
+|---|---|
+| React | [React documentation](https://react.dev), [useEffect](https://react.dev/reference/react/useEffect), [useState](https://react.dev/reference/react/useState), [useMemo](https://react.dev/reference/react/useMemo), [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect) |
+| React Hooks linting | [eslint-plugin-react-hooks](https://www.npmjs.com/package/eslint-plugin-react-hooks) |
+| Next.js | [Next.js documentation](https://nextjs.org/docs), [Next.js 16 upgrade guide](https://nextjs.org/docs/app/guides/upgrading/version-16), [TypeScript configuration](https://nextjs.org/docs/app/api-reference/config/next-config-js/typescript), [Image configuration](https://nextjs.org/docs/app/api-reference/components/image#configuration-options) |
+| Historical Next.js behavior | [Next.js 15 ESLint configuration](https://nextjs.org/docs/15/app/api-reference/config/next-config-js/eslint) |
+| ESLint | [ESLint configuration files](https://eslint.org/docs/latest/use/configure/configuration-files), [ESLint migration to flat config](https://eslint.org/docs/latest/use/configure/migration-guide) |
+| TypeScript | [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/), [TSConfig reference](https://www.typescriptlang.org/tsconfig/), [TypeScript release notes](https://devblogs.microsoft.com/typescript/) |
+| npm | [npm CLI documentation](https://docs.npmjs.com/cli/), [npm audit](https://docs.npmjs.com/cli/commands/npm-audit), [peer dependency settings](https://docs.npmjs.com/cli/using-npm/config#strict-peer-deps) |
+| Yarn Classic | [Yarn Classic documentation](https://classic.yarnpkg.com/en/docs/), [yarn audit](https://classic.yarnpkg.com/en/docs/cli/audit/), [yarn outdated](https://classic.yarnpkg.com/en/docs/cli/outdated/), [yarn why](https://classic.yarnpkg.com/en/docs/cli/why/) |
+| pnpm | [pnpm documentation](https://pnpm.io/), [pnpm audit](https://pnpm.io/cli/audit), [pnpm why](https://pnpm.io/cli/why), [pnpm workspaces](https://pnpm.io/workspaces) |
+| Node.js | [Node.js API documentation](https://nodejs.org/docs/latest/api/), [Node.js package guidance](https://nodejs.org/en/learn/getting-started/packages) |
+| Monorepos | [npm workspaces](https://docs.npmjs.com/cli/using-npm/workspaces), [Yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/), [pnpm workspaces](https://pnpm.io/workspaces), [Turborepo documentation](https://turbo.build/docs), [Nx documentation](https://nx.dev/docs) |
+| tRPC | [tRPC documentation](https://trpc.io/docs), [Context](https://trpc.io/docs/server/context), [Procedures](https://trpc.io/docs/server/procedures), [Error handling](https://trpc.io/docs/server/error-handling) |
+| TanStack Query | [TanStack Query documentation](https://tanstack.com/query/latest/docs/framework/react/overview), [Query keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys), [SSR and hydration](https://tanstack.com/query/latest/docs/framework/react/guides/ssr) |
+| Prisma + PostgreSQL | [Prisma documentation](https://www.prisma.io/docs/orm), [Prisma Migrate](https://www.prisma.io/docs/orm/prisma-migrate), [PostgreSQL documentation](https://www.postgresql.org/docs/), [PostgreSQL EXPLAIN](https://www.postgresql.org/docs/current/using-explain.html) |
+| NestJS | [NestJS documentation](https://docs.nestjs.com/), [Modules](https://docs.nestjs.com/modules), [Validation](https://docs.nestjs.com/techniques/validation), [Exception filters](https://docs.nestjs.com/exception-filters) |
+| Vite | [Vite Guide](https://vite.dev/guide/), [Environment variables](https://vite.dev/guide/env-and-mode), [Vite config](https://vite.dev/config/) |
+| Tailwind CSS | [Tailwind documentation](https://tailwindcss.com/docs), [Tailwind v4 upgrade guide](https://tailwindcss.com/docs/upgrade-guide) |
+| Angular | [Angular documentation](https://angular.dev/overview), [Angular version compatibility](https://angular.dev/reference/versions), [Angular CLI](https://angular.dev/cli) |
+| Testing | [Vitest documentation](https://vitest.dev/guide/), [Jest documentation](https://jestjs.io/docs/getting-started), [Playwright documentation](https://playwright.dev/docs/intro) |
+| react-to-print | [Official repository](https://github.com/MatthewHerbst/react-to-print), [v3 changelog](https://github.com/MatthewHerbst/react-to-print/blob/v3.3.0/CHANGELOG.md) |
+| Formik | [Formik Form API](https://formik.org/docs/api/form) |
+| Radix UI | [Radix Primitives documentation](https://www.radix-ui.com/primitives/docs/overview/introduction) |
+| shadcn/ui | [shadcn CLI](https://ui.shadcn.com/docs/cli), [Radix migration](https://ui.shadcn.com/docs/cli#migrate-radix), [Tailwind v4 migration](https://ui.shadcn.com/docs/tailwind-v4) |
+
+For a library-specific issue, prioritize the library's official documentation, release notes, changelog, and migration guide. If the official sources do not cover the case, resolve it from the actual project context without writing to this knowledge base.
+
+---
+
+## Articles
+
+| File | Stacks | Content |
+|---|---|---|
+| [`react-patterns.md`](./react-patterns.md) | React 19, React Hooks | Effects, derived state, async UI strategy, Suspense boundaries, custom-hook extraction, state mutation |
+| [`nextjs-pitfalls.md`](./nextjs-pitfalls.md) | Next.js 16 | Build/lint changes, config schema drift, Server/Client boundaries, route loading/errors, hydration |
+| [`eslint-migration.md`](./eslint-migration.md) | ESLint 9, Flat Config | Flat config migration, masking, `resolutions`, inline suppressions |
+| [`typescript-patterns.md`](./typescript-patterns.md) | TypeScript Strict | Imports, suppressions, refs, discriminated UI states, runtime validation, null safety |
+| [`dependency-guide.md`](./dependency-guide.md) | npm/yarn/pnpm | Safe update model, dependency analysis, audit interpretation |
+| [`upgrade-fallout.md`](./upgrade-fallout.md) | Multi-stack | Upgrade fallout: scripts, config, new lint rules, validation |
+| [`migration-guides.md`](./migration-guides.md) | Libraries | `react-to-print` v3, Formik + React 19, Radix UI |
+| [`nodejs-patterns.md`](./nodejs-patterns.md) | Node.js | Runtime alignment, ESM/CJS, environment handling, async failures, script portability |
+| [`package-manager-patterns.md`](./package-manager-patterns.md) | npm, Yarn, pnpm | Lockfiles, peers, overrides, audit, workspaces, immutable installs |
+| [`monorepo-patterns.md`](./monorepo-patterns.md) | npm/Yarn/pnpm workspaces, Turbo, Nx | Package boundaries, dependency resolution, shared configs, cache hygiene |
+| [`trpc-patterns.md`](./trpc-patterns.md) | tRPC | Context/auth, input validation, errors, type integrity, router design, transport |
+| [`tanstack-patterns.md`](./tanstack-patterns.md) | TanStack Query | Query ownership, keys, invalidation, async UI states, caching, SSR hydration, cancellation, optimistic updates |
+| [`prisma-postgresql-patterns.md`](./prisma-postgresql-patterns.md) | Prisma, PostgreSQL | Generation drift, migrations, query loading, transactions, indexes, pooling |
+| [`nestjs-patterns.md`](./nestjs-patterns.md) | NestJS | Modules, DI, validation, guards, exceptions, configuration, request scope |
+| [`vite-patterns.md`](./vite-patterns.md) | Vite | Env exposure, base paths, aliases, ESM/CJS, optimizer cache, plugins, React integration |
+| [`tailwind-shadcn-patterns.md`](./tailwind-shadcn-patterns.md) | Tailwind CSS, shadcn/ui | v3/v4 migration, source scanning, tokens, dependencies, themes, design-system reuse |
+| [`testing-patterns.md`](./testing-patterns.md) | Vitest, Jest, Playwright | Environments, determinism, mocks, async UI behavior, isolation, CI parity, validation |
+| [`angular-patterns.md`](./angular-patterns.md) | Angular | Standalone APIs, DI, signals/RxJS, forms, HTTP, routing, version alignment |
+
+---
+
+## Maintenance (Dev Booster Maintainers Only)
+
+This base is manually curated. Only Dev Booster maintainers add, update, or remove content.

package/template/.devbooster/hub/knowledge/migration-guides.md

@@ -0,0 +1,137 @@
+# 🚚 Migration Guides
+
+> **Purpose:** Migration guides for specific libraries with breaking changes observed in real projects
+> **Primary official sources:** [react-to-print repository](https://github.com/MatthewHerbst/react-to-print) · [React documentation](https://react.dev/) · [Radix UI documentation](https://www.radix-ui.com/) · [shadcn/ui documentation](https://ui.shadcn.com/docs)
+
+## Project Convention Decision Rule
+
+Before applying this guidance, verify the installed versions, local rules, existing abstractions, configuration, and tests. Preserve a valid established project convention; do not replace it only because another documented approach is also valid. Use official sources to verify API behavior, compatibility, constraints, and migrations. Recommend a change only when the developer requests it or evidence shows the current approach is incompatible, unsafe, deprecated, broken, or responsible for a verified issue.
+
+---
+
+## Index
+
+1. [react-to-print v2 → v3](#react-to-print-v2--v3)
+2. [Formik + React 19 — HTML Form Types](#formik--react-19)
+3. [Radix UI — Meta-package vs Individual Packages](#radix-ui-meta-package)
+4. [shadcn/ui — Missing Dependencies](#shadcn-ui-missing-dependencies)
+
+---
+
+## react-to-print v2 → v3
+
+### Problem
+The `useReactToPrint` API changed significantly from v2 to v3. The `content` option was renamed to `contentRef` and now receives a ref object rather than a callback.
+
+### Code (symptom)
+```tsx
+// BEFORE (v2)
+useReactToPrint({ content: () => ref.current })
+
+// AFTER (v3)
+useReactToPrint({ contentRef: ref })
+```
+
+### Expected type error
+```
+'content' does not exist in type 'UseReactToPrintOptions'
+```
+
+### Fix
+```tsx
+const contentRef = useRef<HTMLDivElement>(null)
+const print = useReactToPrint({ contentRef })
+
+// Attach contentRef to the element to print, then call print from the print trigger.
+```
+
+### Scope
+The documented v3 breaking change is the rename and type change from `content` to `contentRef`. Review the v3 migration notes for its other breaking changes.
+
+---
+
+## Formik + React 19
+
+### Problem
+React 19 form type errors can result from misaligned `react`, `react-dom`, and `@types/react` versions, including duplicate React type packages. Do not assume that a Formik version alone is the cause.
+
+### Type error
+```
+Type '{ children: Element; }' is missing the following properties from type
+'Pick<DetailedHTMLProps<FormHTMLAttributes<HTMLFormElement>, ...>':
+placeholder, onPointerEnterCapture, onPointerLeaveCapture
+```
+
+### Check first
+1. Align the installed `react`, `react-dom`, `@types/react`, and `@types/react-dom` versions.
+2. Inspect the lockfile and dependency tree for duplicate or incompatible React type packages.
+3. Re-run type checking before changing form markup.
+
+### Native form fallback
+Use a native `<form>` only when type alignment does not resolve the issue, and preserve the semantics provided by Formik's `<Form>`:
+
+```tsx
+<form
+  onReset={formik.handleReset}
+  onSubmit={formik.handleSubmit}
+  {...formProps}
+>
+  {children}
+</form>
+```
+
+Preserve any required forwarded props and refs. `noValidate` is a standard HTML form attribute and can be passed directly when needed.
+
+---
+
+## Radix UI Meta-package
+
+### Problem
+A component can import either the unified `radix-ui` package or an individual `@radix-ui/react-*` package. The required installation depends on the actual import specifier in the component source.
+
+### Symptom
+```
+Cannot find module 'radix-ui'
+```
+
+### Choose the matching package
+```bash
+# Source imports from "radix-ui"
+yarn add radix-ui
+
+# Source imports from "@radix-ui/react-dialog"
+yarn add @radix-ui/react-dialog
+```
+
+### Migration
+For existing shadcn/ui components that use individual Radix imports, use the documented Radix migration to rewrite imports before removing individual packages. Do not add the unified package solely because another component uses a different import style.
+
+---
+
+## shadcn/ui — Missing Dependencies
+
+### Problem
+The standard shadcn CLI installs the dependencies required by the component it adds. Manually copied components, custom registries, or incomplete installs may still reference packages that are absent.
+
+### Component-specific patterns
+- `class-variance-authority` — only when the component calls `cva()`
+- `tailwind-merge` — only when the project utility imports it
+- `lucide-react` — only when the component imports Lucide icons
+- `tailwindcss-animate` — legacy Tailwind v3 animation plugin
+- `tw-animate-css` — Tailwind v4 animation package
+
+### Fix
+Inspect the component imports and registry metadata, then install only the missing direct dependency. For animations, match the package to the Tailwind version:
+
+```bash
+# Tailwind v3
+yarn add -D tailwindcss-animate
+
+# Tailwind v4
+yarn add -D tw-animate-css
+```
+
+### Missing dependency symptom
+```
+Cannot find module 'class-variance-authority'
+```

package/template/.devbooster/hub/knowledge/monorepo-patterns.md

@@ -0,0 +1,121 @@
+# Monorepo Patterns
+
+> **Purpose:** Keep workspace packages, dependency resolution, shared configuration, and task execution reproducible in JavaScript/TypeScript monorepos.
+> **Primary official sources:** [npm workspaces](https://docs.npmjs.com/cli/v11/using-npm/workspaces) · [Yarn workspaces](https://yarnpkg.com/features/workspaces) · [pnpm workspaces](https://pnpm.io/workspaces) · [Turborepo documentation](https://turborepo.com/docs) · [Nx documentation](https://nx.dev/)
+
+## Project Convention Decision Rule
+
+Before applying this guidance, verify the installed versions, local rules, existing abstractions, configuration, lockfile, workspace layout, and tests. Preserve a valid established project convention; do not replace it only because another documented approach is also valid. Use official sources to verify API behavior, compatibility, constraints, and migrations. Recommend a change only when the developer requests it or evidence shows the current approach is incompatible, unsafe, deprecated, broken, or responsible for a verified issue.
+
+---
+
+## Table of Contents
+
+1. [Workspace Package Boundaries](#workspace-package-boundaries)
+2. [Declared Dependencies and Phantom Dependencies](#declared-dependencies-and-phantom-dependencies)
+3. [Shared Configuration Resolution](#shared-configuration-resolution)
+4. [Task Runner Cache Hygiene](#task-runner-cache-hygiene)
+5. [Workspace-Aware Commands](#workspace-aware-commands)
+6. [Lockfile and Root Toolchain Consistency](#lockfile-and-root-toolchain-consistency)
+
+---
+
+## Workspace Package Boundaries
+
+### Symptom
+A package imports source files from another package's internals, builds only by accident, or cannot be independently published, tested, or consumed.
+
+### Verify first
+Check each workspace's `package.json`: `name`, `private`, `exports` (when published), build output, and declared dependencies. Verify that consumers import the package's public name rather than a relative path into its source tree. Workspace discovery is manager-specific; see [npm workspaces](https://docs.npmjs.com/cli/v11/using-npm/workspaces), [Yarn workspaces](https://yarnpkg.com/features/workspaces), and [pnpm workspaces](https://pnpm.io/workspaces).
+
+### Fix
+- Give each independently consumed unit an explicit package boundary and public API.
+- Import internal packages by package name, not by relative paths that bypass packaging and export rules.
+- Mark packages not intended for publication as `private`.
+- Keep generated output, package entry points, and export maps consistent with the files produced by the package build.
+
+---
+
+## Declared Dependencies and Phantom Dependencies
+
+### Symptom
+A package builds locally but fails in isolation, after a clean install, or when consumed outside the repository.
+
+### Problem
+The package imports a dependency that is only available because another workspace or a hoisted install placed it nearby. This is a phantom dependency.
+
+### Fix
+- Declare every runtime, build-time, and type dependency in the package that directly imports it, using the appropriate dependency section.
+- Declare internal workspace relationships explicitly and use the package manager's supported workspace protocol where applicable.
+- Do not rely on hoisting layout, transitive dependencies, or root-level tooling to make an import resolve.
+
+### Verify first
+Install from a clean checkout and test/build the affected workspace directly. For publishable packages, validate the packed artifact in a clean temporary consumer. pnpm explains why workspace linking and protocol use are explicit in [workspace settings](https://pnpm.io/workspaces#workspace-protocol-workspace).
+
+---
+
+## Shared Configuration Resolution
+
+### Symptom
+A linter, TypeScript compiler, test runner, or bundler behaves differently when launched from the root versus a workspace.
+
+### Verify first
+Determine which config file is found, the current working directory, and whether plugins/presets resolve from the root, the workspace, or the config package. Check the tool's own configuration-resolution documentation before moving files or adding duplicate dependencies.
+
+### Fix
+- Make shared configuration a versioned workspace package or a clearly owned root configuration, according to the consuming tool's resolution model.
+- Reference shared config through supported package/config mechanisms rather than brittle relative paths when the tool supports it.
+- Put plugins and parsers where the resolver expects them; do not depend on incidental hoisting.
+- Run configuration-sensitive commands from the same scope in local development and CI.
+
+For TypeScript project structure and references, use the [TypeScript project references handbook](https://www.typescriptlang.org/docs/handbook/project-references.html).
+
+---
+
+## Task Runner Cache Hygiene
+
+### Symptom
+A cached task returns stale output, misses a required rebuild after configuration changes, or appears successful without producing expected artifacts.
+
+### Verify first
+For the affected task, list its declared inputs, environment variables, dependency tasks, outputs, working directory, and cache mode. Turborepo documents task inputs/outputs and caching in [Turborepo caching](https://turborepo.com/docs/crafting-your-repository/caching); Nx documents inputs and task caching in [Nx cache inputs](https://nx.dev/concepts/how-caching-works#inputs).
+
+### Fix
+- Declare outputs precisely so restored cache artifacts match what downstream tasks consume.
+- Include relevant source, lockfile, configuration, generated-schema, and environment inputs in the cache definition.
+- Exclude secrets from cache keys and outputs; use non-secret version markers when configuration must affect caching.
+- Make task dependencies explicit rather than relying on execution order or existing files.
+- Clear or bypass cache only to diagnose incorrect cache inputs; repair the task definition before re-enabling it.
+
+---
+
+## Workspace-Aware Commands
+
+### Symptom
+A command runs in every package, runs only at the root, resolves the wrong binary, or changes dependencies in an unintended workspace.
+
+### Verify first
+Use the package manager's workspace-listing capability and confirm the target package name. Review the exact command's workspace flags rather than assuming equivalent syntax across managers. npm provides [workspace command guidance](https://docs.npmjs.com/cli/v11/using-npm/workspaces#running-commands-in-the-context-of-workspaces).
+
+### Fix
+- Prefer explicit workspace/package selectors for focused install, run, test, and build commands.
+- Use recursive/all-workspace execution only when the task is designed to be independent or ordered by declared dependencies.
+- Keep root scripts as orchestration entry points and package scripts as package-local behavior.
+- In CI, log the selected workspace and command to make scope errors visible.
+
+---
+
+## Lockfile and Root Toolchain Consistency
+
+### Problem
+Different packages or CI jobs use different package-manager versions, lockfile policies, Node versions, or root tool versions, producing incompatible dependency trees and task results.
+
+### Fix
+- Maintain a single root lockfile and use the repository's declared package manager everywhere.
+- Pin or otherwise declare the package-manager version with the repository-supported mechanism; Corepack recognizes `packageManager` metadata. See [Node.js Corepack](https://nodejs.org/docs/latest/api/corepack.html).
+- Align Node selection across local development, CI, and containers with the root `engines` policy.
+- Put monorepo-wide task-runner and shared-tool configuration under clear root ownership.
+- Validate CI with a non-mutating install mode, then execute workspace-aware checks from a clean checkout.
+
+### Verify first
+Confirm that a clean clone has one expected lockfile, uses the intended manager/runtime, and completes a focused package build followed by the repository's dependency-aware build. Any lockfile modification during validation is a reproducibility failure to investigate, not a change to commit automatically.

package/template/.devbooster/hub/knowledge/nestjs-patterns.md

@@ -0,0 +1,185 @@
+# NestJS Patterns
+
+> **Purpose:** Practical patterns for dependable NestJS application boundaries.
+> **Primary official sources:** [Nest modules](https://docs.nestjs.com/modules) · [Nest providers](https://docs.nestjs.com/providers) · [Nest validation](https://docs.nestjs.com/techniques/validation) · [Nest authentication](https://docs.nestjs.com/security/authentication) · [Nest exception filters](https://docs.nestjs.com/exception-filters) · [Nest configuration](https://docs.nestjs.com/techniques/configuration)
+
+## Project Convention Decision Rule
+
+Before applying this guidance, verify the installed versions, local rules, existing abstractions, configuration, and tests. Preserve a valid established project convention; do not replace it only because another documented approach is also valid. Use official sources to verify API behavior, compatibility, constraints, and migrations. Recommend a change only when the developer requests it or evidence shows the current approach is incompatible, unsafe, deprecated, broken, or responsible for a verified issue.
+
+---
+
+## Table of Contents
+
+1. [Module and Provider Visibility](#module-and-provider-visibility)
+2. [Circular Dependencies and forwardRef](#circular-dependencies-and-forwardref)
+3. [Validation Pipes and DTO Transformation](#validation-pipes-and-dto-transformation)
+4. [Authentication Guards and Execution Context](#authentication-guards-and-execution-context)
+5. [Global Exception Filters and Error Contracts](#global-exception-filters-and-error-contracts)
+6. [Configuration and Environment Validation](#configuration-and-environment-validation)
+7. [Request-Scoped Provider Caveats](#request-scoped-provider-caveats)
+
+---
+
+## Module and Provider Visibility
+
+### Symptom
+Nest cannot resolve a dependency even though a provider exists elsewhere, or a feature accidentally depends on an implementation that should be private.
+
+### Verify first
+- Read the consuming module's `imports`, the providing module's `providers`, and its `exports`.
+- Confirm injection tokens match exactly, especially for custom providers and interfaces (which do not exist at runtime).
+- Check whether the module was registered in the application graph rather than merely imported by a TypeScript file.
+
+### Fix
+- Keep a provider private by default. Export only the provider token or service intended as the module's public API.
+- Import the module that exports the provider; adding the provider directly to a second module creates a separate instance and may hide the ownership problem.
+- Use explicit tokens for abstractions and bind them in one composition location.
+
+### Verify
+- Bootstrap a test module using the same imports as the production consumer.
+- Confirm stateful providers have the intended instance lifetime.
+
+*Sources: [Nest modules](https://docs.nestjs.com/modules), [Nest custom providers](https://docs.nestjs.com/fundamentals/custom-providers).*
+
+---
+
+## Circular Dependencies and forwardRef
+
+### Problem
+Two providers or modules require each other, leading to unresolved dependencies, undefined imports, or tightly coupled business behavior.
+
+### Verify first
+- Distinguish a Nest dependency cycle from a TypeScript import cycle; inspect the dependency direction and runtime tokens.
+- Identify whether the services are coordinating two responsibilities that should be extracted behind a third service, event, or interface.
+
+### Fix
+- Prefer removing the cycle by extracting the shared orchestration or introducing a narrower dependency direction.
+- Use `forwardRef(() => Dependency)` only when the cycle is intentional, limited, and understood. Apply it at the matching module/provider injection point.
+- Do not rely on constructor order between circular providers; Nest documents that instantiation order is indeterminate.
+
+### Verify
+- Bootstrap the affected module and exercise both paths through the cycle.
+- Check that unit tests can replace each side independently; difficult substitution is a sign that the boundary remains too coupled.
+
+*Source: [Nest circular dependency fundamentals](https://docs.nestjs.com/fundamentals/circular-dependency).*
+
+---
+
+## Validation Pipes and DTO Transformation
+
+### Symptom
+Requests accept unexpected fields, route/query values retain string types, nested objects are not validated, or validation behavior differs between endpoints.
+
+### Verify first
+- Identify the transport and source: body, query, params, headers, or a message payload.
+- Confirm the runtime DTO is a concrete class with `class-validator` decorators; TypeScript types/interfaces alone cannot be reflected for validation.
+- Test representative invalid input, unknown fields, nested DTOs, and coercion edge cases such as empty strings and dates.
+
+### Fix
+- Apply a global `ValidationPipe` only after choosing an API policy for `whitelist`, `forbidNonWhitelisted`, and transformation.
+- Use DTO classes for input contracts. For nested values, provide type metadata such as `@Type(() => ChildDto)` where required by `class-transformer`.
+- Enable `transform` when handlers need converted primitive route/query values, but declare expected types and test coercion. Transformation is not a substitute for semantic validation.
+- Keep validation rules at the boundary; preserve domain-specific invariants in application/domain logic as well.
+
+### Verify
+- Add end-to-end tests asserting the status code and error body for malformed input.
+- Confirm successful inputs arrive at the handler with the expected runtime types.
+
+*Sources: [Nest validation](https://docs.nestjs.com/techniques/validation), [class-validator](https://github.com/typestack/class-validator), [class-transformer](https://github.com/typestack/class-transformer).*
+
+---
+
+## Authentication Guards and Execution Context
+
+### Problem
+Authentication works for one transport but is bypassed or reads the wrong request object for another; authorization logic becomes duplicated across controllers.
+
+### Verify first
+- Identify the active transport and context: HTTP, GraphQL, WebSocket, or RPC. `ExecutionContext` exposes different arguments for each.
+- Separate authentication (establishing identity) from authorization (deciding access).
+- Define which routes are public and how metadata inheritance at controller and handler levels should work.
+
+### Fix
+- Put identity extraction and verification in a guard or strategy appropriate to the transport.
+- Use `ExecutionContext` APIs rather than assuming `switchToHttp().getRequest()` is valid everywhere.
+- Express authorization requirements as explicit metadata and enforce them in a guard. Keep resource-level checks close to the use case when they require loading the resource.
+- Attach only the normalized identity/claims needed downstream; do not treat unverified decoded token data as authenticated identity.
+
+### Verify
+- Test absent, malformed, expired, and valid credentials plus forbidden-but-authenticated access.
+- Exercise every supported transport and both controller- and method-level metadata paths.
+
+*Sources: [Nest guards](https://docs.nestjs.com/guards), [Nest execution context](https://docs.nestjs.com/fundamentals/execution-context), [Nest authorization](https://docs.nestjs.com/security/authorization).*
+
+---
+
+## Global Exception Filters and Error Contracts
+
+### Symptom
+Clients receive inconsistent error bodies, internal details leak, or exceptions from different layers map to arbitrary status codes.
+
+### Verify first
+- Define the public error contract: status, stable machine-readable code, safe message, field errors where applicable, and correlation/request identifier policy.
+- Identify adapter behavior and existing global filters/interceptors. A filter that writes an HTTP response is transport-specific.
+- Classify expected domain/application errors separately from programming errors and infrastructure failures.
+
+### Fix
+- Use Nest's built-in HTTP exceptions for straightforward transport errors.
+- Add a global filter to translate known application errors into one documented public contract, log unexpected errors with safe context, and avoid exposing stack traces or secrets.
+- Preserve the original cause for observability when wrapping errors, but do not return it to clients.
+- Avoid catching every exception inside controllers; doing so fragments error policy and can hide defects.
+
+### Verify
+- Test validation, not-found, forbidden, conflict, and unexpected-error responses.
+- Ensure production responses do not contain stack traces, tokens, database errors, or internal file paths.
+
+*Sources: [Nest exception filters](https://docs.nestjs.com/exception-filters), [Nest validation errors](https://docs.nestjs.com/techniques/validation#disable-detailed-errors).*
+
+---
+
+## Configuration and Environment Validation
+
+### Problem
+The application starts with missing or malformed configuration, discovers it only under traffic, or reads environment variables throughout business code.
+
+### Verify first
+- Inventory required settings, optional settings with defaults, secret sources, and environment-specific constraints.
+- Confirm how configuration is loaded in each runtime; `.env` files are not automatically a production secret-management strategy.
+- Decide which invalid settings must fail startup versus which can be disabled safely.
+
+### Fix
+- Centralize configuration with `@nestjs/config` and expose typed, focused configuration access to consumers.
+- Validate required environment values during startup with a schema or custom validation function. Validate format and range, not only presence.
+- Keep secrets out of logs, errors, repository files, and client-side configuration.
+- Prefer injecting configuration over reading `process.env` across arbitrary services, which makes tests and runtime behavior harder to control.
+
+### Verify
+- Start the application with missing, malformed, and valid configurations.
+- Confirm failures identify the setting safely without printing its secret value.
+
+*Source: [Nest configuration](https://docs.nestjs.com/techniques/configuration).*
+
+---
+
+## Request-Scoped Provider Caveats
+
+### Problem
+A request-scoped dependency unexpectedly increases latency/memory use, causes broad scope propagation, or behaves inconsistently in non-HTTP code.
+
+### Verify first
+- Confirm that mutable per-request state cannot instead be passed as an explicit argument or carried by a transport context.
+- Inspect the dependency tree: a request-scoped provider can make dependent providers request-scoped.
+- Measure the allocation and latency impact under expected concurrency, and identify whether the code also runs in jobs, events, or WebSockets.
+
+### Fix
+- Keep services singleton-scoped by default; make dependencies request-scoped only for a concrete per-request lifecycle requirement.
+- Pass request-specific values explicitly when practical. This preserves singleton reuse and makes behavior easier to test.
+- For non-singleton scenarios, use Nest's documented context/request-provider mechanisms rather than assuming an HTTP request exists.
+- Do not use request scope as a substitute for authorization isolation or transaction management.
+
+### Verify
+- Load-test the affected route and check instance lifecycle behavior.
+- Exercise background and non-HTTP invocation paths if the provider is shared with them.
+
+*Sources: [Nest injection scopes](https://docs.nestjs.com/fundamentals/injection-scopes), [Nest request lifecycle](https://docs.nestjs.com/faq/request-lifecycle).*