Build & Development Commands

• All code must target Node.js LTS (currently 22.14.0) using ESM modules and the NodeNext module resolution strategy.
• Use pnpm as the package manager. Prefer pnpm install and pnpm dlx for running and installing tools.
• Ensure all projects include appropriate build scripts, including "build", "lint", "test", and "typecheck" commands.
• Projects must be configured to use strict TypeScript settings (strict: true, no any, no implicit any, etc.).

Testing Guidelines

• Write unit tests for all business logic using Jest. Each test file must achieve high coverage and provide meaningful assertions.
• Use descriptive describe and it/test block names to clarify test intent.
• Mock external dependencies (e.g., APIs, I/O) cleanly using dependency injection or mocking libraries.
• Avoid integration tests unless explicitly required by context. Keep tests deterministic and fast.
• Always test pure functions thoroughly with edge cases, expected input ranges, and invalid inputs.

Code Style & Guidelines

• Always prefer functional programming principles:
  • Use pure functions where possible.
  • Avoid shared mutable state and side effects unless contextually necessary (e.g., logging, metrics, filesystem).
  • Use composition, higher-order functions, and immutability patterns.
• Classes are permitted but only when necessary; ensure they adhere to SOLID principles and encapsulate mutable state carefully.
• Avoid any in all forms. Use strict and explicit types for all parameters, return values, and data structures.
• Use ESLint with strict rules enabled. Format all code automatically using Prettier.
• Organize code into small, reusable, and well-named modules. Prefer named exports and maintain one purpose per file.
• Use clear, structured error handling with typed Error classes and consistent throw statements.
• Isolate side effects into specific files or functions. Never mix I/O logic with core business logic.
• Validate all input and output using schema validators like zod, yup, or io-ts.
• Ask for missing context before proceeding with code generation or review, including related interfaces, file structure, and requirements.

Documentation Guidelines

• Include inline comments for any non-obvious logic or complex flows.
• Document public functions, exports, and types using TSDoc or standard JSDoc conventions.
• Add README files to packages with usage examples, expected inputs/outputs, and integration notes.
• Provide changelogs using changesets or equivalent tooling for versioned packages.
• When reviewing or generating code, explain any assumptions made and reasoning behind specific patterns or architectural choices.