dev-booster 1.18.0 → 1.18.2

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).*

package/template/.devbooster/hub/knowledge/nextjs-pitfalls.md

@@ -0,0 +1,226 @@
+# ▲ Next.js Pitfalls
+
+> **Purpose:** Common pitfalls and issues in Next.js 16+ projects
+> **Primary official sources:** [Next.js TypeScript configuration](https://nextjs.org/docs/app/api-reference/config/next-config-js/typescript) · [Next.js 16 upgrade guide](https://nextjs.org/docs/app/guides/upgrading/version-16) · [Next.js Image configuration](https://nextjs.org/docs/app/api-reference/components/image#configuration-options)
+
+## Project Convention Decision Rule
+
+Before applying this guidance, verify the installed versions, router and rendering model, 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. [Framework-level Masking — ignoreBuildErrors](#framework-level-masking)
+2. [Legacy Build-time Lint Masking — Next.js 15 and Earlier](#legacy-build-time-lint-masking)
+3. [Broken Lint Script After a Next.js 16 Upgrade](#broken-lint-script-after-a-nextjs-16-upgrade)
+4. [Invalid next.config Properties](#invalid-nextconfig-properties)
+5. [TSConfig Changes Triggered by Next.js](#tsconfig-changes-triggered-by-nextjs)
+6. [New Lint Findings After an Upgrade](#new-lint-findings-after-an-upgrade)
+7. [Warnings Need Triage](#warnings-need-triage)
+8. [Choose Server and Client Boundaries Deliberately](#choose-server-and-client-boundaries-deliberately)
+9. [Use Route Loading and Error Boundaries Before Rebuilding Them](#use-route-loading-and-error-boundaries-before-rebuilding-them)
+10. [Avoid Hydration Mismatches by Preserving Initial Output](#avoid-hydration-mismatches-by-preserving-initial-output)
+
+---
+
+## Framework-level Masking
+
+### Problem
+The `typescript.ignoreBuildErrors: true` option in `next.config.*` skips Next.js's built-in TypeScript type-checking step during production builds. It does not run the check and suppress its errors, so it can allow type errors to reach deployment.
+
+*Source: [Next.js TypeScript configuration](https://nextjs.org/docs/app/api-reference/config/next-config-js/typescript)*
+
+> The official Next.js documentation warns: "If disabled, be sure you are running type checks as part of your build or deploy process, otherwise this can be very dangerous."
+
+### Code (symptom)
+```js
+// next.config.js — bypasses Next.js type checking
+typescript: { ignoreBuildErrors: true }
+```
+
+### Fix
+Remove the flag; `false` is the default:
+```js
+module.exports = {
+  typescript: {
+    ignoreBuildErrors: false,
+  },
+}
+```
+
+If a project temporarily keeps the flag, run an explicit type check such as `tsc --noEmit` in CI or the deployment pipeline.
+
+---
+
+## Legacy Build-time Lint Masking
+
+**Evidence:** Field-validated in a real audit.
+
+### Applicability
+Next.js 15 and earlier. The `eslint.ignoreDuringBuilds` option was supported in these versions and allowed production builds to complete with ESLint errors.
+
+*Source: [Next.js 15 ESLint configuration](https://nextjs.org/docs/15/app/api-reference/config/next-config-js/eslint)*
+
+### Code (symptom)
+```js
+module.exports = {
+  eslint: {
+    ignoreDuringBuilds: true,
+  },
+}
+```
+
+### Why it matters
+This setting bypasses Next.js's built-in build-time lint failure. It may have been introduced as a temporary deployment workaround, but it hides lint failures unless ESLint runs independently in CI or another verified workflow.
+
+### Version boundary
+Next.js 16 removed `next lint`, build-time linting, and the `eslint` key in `next.config.*`. For Next.js 16+, remove this legacy config and run ESLint directly as a separate validation command.
+
+---
+
+## Broken Lint Script After a Next.js 16 Upgrade
+
+### Problem
+Starting with Next.js 16, `next lint` is removed. `next build` no longer runs linting, and the `eslint` key in `next.config.*` is removed.
+
+Invoking the removed command can produce an error such as:
+```
+Invalid project directory provided, no such directory: .../lint
+```
+
+### Fix
+Run ESLint directly and make linting a separate CI or deployment step:
+```json
+{
+  "scripts": {
+    "lint": "eslint ."
+  }
+}
+```
+
+For flat-config setup and migration details, see [ESLint Migration](./eslint-migration.md).
+
+---
+
+## Invalid next.config Properties
+
+### Problem
+A property in an unsupported location in `next.config.*` can produce a configuration warning or be ignored. For example, `unoptimized` is not a top-level Next.js config option.
+
+### Code (symptom)
+```js
+// Invalid location
+module.exports = { unoptimized: true }
+
+// Valid location
+module.exports = { images: { unoptimized: true } }
+```
+
+### Fix
+Use the documented `images.unoptimized` option:
+```js
+module.exports = {
+  images: {
+    unoptimized: true,
+  },
+}
+```
+
+---
+
+## TSConfig Changes Triggered by Next.js
+
+### Problem
+When TypeScript is added to a project, `next dev` and `next build` can create or update `tsconfig.json` with recommended settings and generated-type includes.
+
+### Handling
+- Review the complete `tsconfig.json` diff and identify why each change was made.
+- Keep required generated-type includes, such as `.next/types/**/*.ts`, when the project uses Next.js route-aware types.
+- Validate compiler-option changes, including `moduleResolution`, against the project's Next.js and TypeScript versions before accepting or reverting them.
+- Commit intentional configuration changes so they are visible in review.
+
+---
+
+## New Lint Findings After an Upgrade
+
+### Problem
+After migrating to ESLint flat config or updating Next.js, ESLint, or plugins, new rules or changed analysis can reveal existing issues or introduce upgrade-specific incompatibilities.
+
+### Common examples
+- A callback referenced before declaration
+- Non-deterministic logic during render, such as `Math.random()` in a component body
+- An unused import that was previously not reported
+
+### Handling
+1. Analyze each finding individually.
+2. Classify it as a pre-existing issue now detected, a configuration change, or an upgrade regression.
+3. Apply a specific fix or document a narrowly justified exception.
+
+---
+
+## Warnings Need Triage
+
+### Problem
+A successful build can still emit warnings about configuration, deprecations, or behavior that affects production.
+
+### Checklist
+After a framework upgrade:
+1. Run `next build` and capture the full output.
+2. Review warnings as well as errors.
+3. Determine the source, impact, and owner of each warning.
+4. Fix the warning or document an accepted disposition according to the project's release policy.
+
+### Rule of thumb
+**A passing build with warnings requires triage; warnings are neither automatically deploy-blocking nor automatically acceptable.**
+
+---
+
+## Choose Server and Client Boundaries Deliberately
+
+### Decision
+In the App Router, components are Server Components by default. Add `'use client'` only when the component or one of its direct responsibilities requires client-side capabilities such as state, Effects, browser APIs, or event handlers.
+
+### Verify first
+- Identify the active router; do not apply App Router guidance to a Pages Router project.
+- Keep the client boundary as narrow as the existing architecture permits.
+- Inspect existing component boundaries and shared providers before moving a component to the client.
+- Pass serializable props across the Server-to-Client boundary.
+
+Do not convert a server-rendered subtree to a Client Component merely to solve a small interactive concern. Extract the interactive leaf when that preserves the project’s established composition pattern.
+
+*Sources: [Next.js — Server and Client Components](https://nextjs.org/docs/app/getting-started/server-and-client-components) · [Next.js — use client](https://nextjs.org/docs/app/api-reference/directives/use-client)*
+
+---
+
+## Use Route Loading and Error Boundaries Before Rebuilding Them
+
+### Decision
+For App Router route segments, inspect existing `loading.*`, `error.*`, and shared layout conventions before adding component-local loading or error state. These files define framework-native boundaries for the segment and its descendants.
+
+### Verify first
+- Confirm whether the loading state is route-level, component-level, or owned by an existing client query abstraction.
+- Preserve existing fallback, retry, error-reporting, and accessibility conventions.
+- Do not use `loading.*` as a substitute for errors in a client-side mutation or interaction; use the project’s local feedback pattern there.
+- Confirm the required error boundary shape for the installed Next version before creating one.
+
+Use the smallest boundary that gives the intended user experience. A project may intentionally prefer a shared route skeleton or a local component state; preserve either approach when valid.
+
+*Sources: [Next.js — Loading UI and Streaming](https://nextjs.org/docs/app/building-your-application/routing/loading-ui-and-streaming) · [Next.js — Error Handling](https://nextjs.org/docs/app/building-your-application/routing/error-handling)*
+
+---
+
+## Avoid Hydration Mismatches by Preserving Initial Output
+
+### Symptom
+The server-rendered HTML differs from the first client render, producing a hydration warning, discarded markup, or visible flicker.
+
+### Verify first
+Look for browser-only values (`window`, storage, viewport), time, randomness, locale, and data that changes between the server and first client render. Confirm whether the component is intended to render consistently on both sides.
+
+### Fix
+Render the same initial output on server and client, then read browser-only state after mount when necessary. For an intentionally client-only widget, isolate it behind the project’s established client boundary rather than scattering hydration suppressions.
+
+Do not use `suppressHydrationWarning` as a general fix; it is a narrow escape hatch and does not reconcile the underlying output.
+
+*Source: [Next.js — React Hydration Error](https://nextjs.org/docs/messages/react-hydration-error)*

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

@@ -0,0 +1,148 @@
+# Node.js Runtime Patterns
+
+> **Purpose:** Diagnose and prevent common Node.js runtime, module, environment, and script failures.
+> **Primary official sources:** [Node.js documentation](https://nodejs.org/docs/latest/api/) · [npm package.json documentation](https://docs.npmjs.com/cli/v11/configuring-npm/package-json) · [npm scripts documentation](https://docs.npmjs.com/cli/v11/using-npm/scripts)
+
+## Project Convention Decision Rule
+
+Before applying this guidance, verify the installed versions, local rules, existing abstractions, configuration, runtime environment, 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. [Runtime and Engines Misalignment](#runtime-and-engines-misalignment)
+2. [ESM and CommonJS Interoperability](#esm-and-commonjs-interoperability)
+3. [Environment Loading and Validation](#environment-loading-and-validation)
+4. [Unhandled Async Failures](#unhandled-async-failures)
+5. [Portable npm Scripts and Lifecycle Hooks](#portable-npm-scripts-and-lifecycle-hooks)
+6. [Version Manager, CI, and Container Alignment](#version-manager-ci-and-container-alignment)
+
+---
+
+## Runtime and Engines Misalignment
+
+### Symptom
+A command works on one machine but fails in CI or production with syntax errors, unsupported APIs, native-module errors, or an `EBADENGINE` warning/error.
+
+### Verify first
+```sh
+node --version
+npm --version
+node -p "process.version"
+```
+Compare those values with the root `package.json` `engines`, the CI runtime setup, container base image, and any version-manager file. `engines` expresses compatibility metadata; enforcement depends on the package manager and its configuration. See [npm `engines`](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#engines).
+
+### Fix
+- Define a tested Node range in `engines`; use an exact version only when reproducibility requires it.
+- Select a Node version explicitly in CI and containers rather than relying on a runner or image default.
+- Rebuild native dependencies after changing Node versions; do not reuse artifacts built against an incompatible ABI.
+- Keep local version-manager configuration aligned with the supported range.
+
+---
+
+## ESM and CommonJS Interoperability
+
+### Symptom
+`require is not defined`, `ERR_REQUIRE_ESM`, missing named exports, or different behavior between development and production builds.
+
+### Verify first
+Inspect the closest `package.json` for `"type"`, the file extension (`.mjs`, `.cjs`, `.js`), and the dependency's documented exports. Node determines module interpretation from these inputs. See [Node.js modules: packages](https://nodejs.org/docs/latest/api/packages.html) and [ECMAScript modules](https://nodejs.org/docs/latest/api/esm.html).
+
+### Fix
+- Choose one module system for new application code and declare it deliberately with `type` or explicit extensions.
+- In ESM, import CommonJS through its default export when necessary, then read properties from that value.
+- In CommonJS, use `import()` for an ESM-only dependency because synchronous `require()` has compatibility limits.
+- Do not depend on undocumented deep imports or inferred named exports; use the dependency's public export map.
+
+```js
+// CommonJS loading an ESM package
+const loadTool = () => import('an-esm-only-package')
+
+// ESM consuming CommonJS
+import legacyPackage from 'legacy-package'
+const { createClient } = legacyPackage
+```
+
+---
+
+## Environment Loading and Validation
+
+### Symptom
+A service starts with `undefined` configuration, uses development credentials in another environment, or fails only after handling traffic.
+
+### Verify first
+Identify where configuration is loaded, which process owns it, and whether the expected variables are present without printing secrets:
+
+```sh
+node -e "console.log(Boolean(process.env.REQUIRED_SETTING))"
+```
+Node exposes the process environment through [`process.env`](https://nodejs.org/docs/latest/api/process.html#processenv). Recent Node releases also document loading `.env` files with [`--env-file`](https://nodejs.org/docs/latest/api/cli.html#--env-fileconfig); verify availability in the exact Node version in use before relying on it.
+
+### Fix
+- Load configuration before importing or initializing code that reads it.
+- Validate required variables, types, allowed values, and cross-field constraints at process startup; fail with variable names, never secret values.
+- Treat environment values as strings until parsed and validated.
+- Keep secrets out of source control and inject them through the deployment environment or an approved secret mechanism.
+
+---
+
+## Unhandled Async Failures
+
+### Symptom
+A request hangs, an error appears as an unhandled rejection, or the process exits unexpectedly after an async operation fails.
+
+### Verify first
+Trace every promise-returning call to an `await`/`return`/`.catch()`. Review the runtime's unhandled-rejection behavior for the deployed Node version: [Node.js `unhandledRejection`](https://nodejs.org/docs/latest/api/process.html#event-unhandledrejection).
+
+### Fix
+- Await promises inside `try`/`catch` where recovery or translation is needed.
+- Return promises from wrapper functions so callers can observe failures.
+- At process boundaries, log actionable context, release resources, and exit or restart according to the service's supervision model.
+- Do not use a global rejection handler as a substitute for local error handling; it is an observability and last-resort shutdown boundary.
+
+```js
+async function readConfiguration() {
+  try {
+    return await fetchConfiguration()
+  } catch (error) {
+    throw new Error('Configuration could not be loaded', { cause: error })
+  }
+}
+```
+
+---
+
+## Portable npm Scripts and Lifecycle Hooks
+
+### Symptom
+A script passes on one operating system but fails in CI, or an install unexpectedly runs build, download, or publish-related code.
+
+### Verify first
+Review `scripts` and lifecycle names in `package.json`, then run the exact package-manager command used by CI. npm exposes lifecycle context through environment variables and has command-specific lifecycle behavior; see [npm scripts](https://docs.npmjs.com/cli/v11/using-npm/scripts) and [lifecycle scripts](https://docs.npmjs.com/cli/v11/using-npm/scripts#life-cycle-operation-order).
+
+### Fix
+- Prefer Node-based scripts or cross-platform tooling over shell-specific syntax, utilities, and environment assignments.
+- Make each script's inputs and outputs explicit; use package binaries through the package manager rather than assuming global installations.
+- Keep `prepare`, `prepack`, `prepublishOnly`, and install hooks small and intentional. Verify which commands trigger each hook before placing builds or side effects there.
+- Run install commands with lifecycle scripts disabled only as a diagnostic or controlled security measure, not as a permanent workaround for an unknown hook.
+
+---
+
+## Version Manager, CI, and Container Alignment
+
+### Problem
+Node is pinned locally but not in CI or the deployment image, creating a runtime matrix that is neither tested nor supported.
+
+### Fix
+Use one documented source of truth for the supported Node range, and make every execution environment select a compatible runtime:
+
+| Environment | Check |
+| --- | --- |
+| Local development | Version-manager configuration and `node --version` |
+| CI | Explicit setup action/task and cache key including Node and lockfile |
+| Container | Explicit base-image tag and rebuild after runtime changes |
+| Deployment | Platform runtime setting or image runtime |
+
+### Verify first
+Print `node --version` at the start of CI and from the built container. Install from the committed lockfile, then run the same test/build commands that validate local development. For supported release lines and schedules, use the [Node.js release page](https://nodejs.org/en/about/previous-releases).