Initial commit

.cursor/rules/01-global-engineering.mdc

@@ -0,0 +1,93 @@
+---
+description: Core engineering principles, TypeScript, validation, and definition of done
+alwaysApply: true
+---
+
+You are working in a TypeScript-first monorepo for a modern HOA management platform.
+
+## Project structure
+- This repository uses `pnpm` workspaces.
+- Top-level workspace structure:
+  - `apps/web` — Next.js frontend
+  - `apps/api` — Fastify backend
+  - `packages/*` — shared packages
+- Prefer shared packages from the start for reusable concerns such as UI primitives, types, config, i18n, lint config, and tsconfig.
+
+## Core engineering principles
+- Prefer maintainability, clarity, and explicitness over cleverness.
+- Prefer fewer dependencies unless a new dependency is clearly justified.
+- When adding a dependency, always use the latest stable non-beta version.
+- Do not add packages when platform features or existing dependencies are sufficient.
+- Do not introduce anti-patterns.
+- Always follow established patterns in the codebase.
+- If a requested change conflicts with established architecture or patterns, stop and ask before proceeding.
+
+## Planning and execution
+- Before making large changes, propose a brief implementation plan first.
+- “Large changes” include:
+  - modifications across multiple files
+  - schema changes
+  - new dependencies
+  - architecture changes
+  - changes spanning multiple workspaces
+- Prefer small, reviewable changes over sweeping rewrites unless explicitly instructed otherwise.
+
+## File and code organization
+- Prefer modifying existing files over creating new abstractions unless a new abstraction is justified.
+- Avoid speculative abstractions. Generalize after a second real use case.
+- Do not create multi-thousand-line files.
+- Split large files into focused modules before they become unwieldy.
+- Keep modules small and cohesive.
+- Prefer composition over inheritance.
+- Prefer pure functions where practical.
+- Do not create giant utility dumping-ground files.
+
+## TypeScript standards
+- Use strict TypeScript patterns.
+- Avoid `any` unless absolutely unavoidable and explicitly justified.
+- Prefer precise types, discriminated unions, and explicit return types where helpful for maintainability.
+- Shared types and schemas should live in dedicated packages when reused across workspaces.
+- **Always use extensionless imports.** Write `import { foo } from './foo'`, never `import { foo } from './foo.js'`. All TypeScript is processed by `tsx`, Next.js, or Vitest — none require explicit extensions. An ESLint rule enforces this.
+
+## Validation and safety
+- Validate all external boundaries.
+- This includes:
+  - API request validation
+  - API response validation where appropriate
+  - environment variable validation
+  - form validation
+  - file upload validation
+- Use Zod as the default schema validation library unless explicitly directed otherwise.
+- **Examples:** Validate request body and params at every API route boundary; validate environment variables at app startup (e.g. with a Zod schema) and fail fast if invalid.
+
+## Documentation
+- Add JSDoc for every non-trivial function or method, whether internal or exported.
+- JSDoc should be useful, not decorative.
+- Include parameter descriptions, return values, thrown errors where relevant, and examples when useful.
+- Do not add comments that merely restate obvious code.
+
+## Definition of done
+- Before considering work complete, run the smallest relevant checks during development and the full validation suite before finalizing.
+- Full validation includes:
+  - Prettier
+  - lint
+  - typecheck
+  - tests
+- Never mark work complete if lint, typecheck, or tests fail.
+- When finalizing, summarize what checks were run and their outcome.
+
+## Documentation and repo hygiene
+- Keep related documentation up to date when behavior changes.
+- This includes, where relevant:
+  - README files
+  - environment examples
+  - package scripts
+  - API docs
+  - setup docs
+- New apps or packages should include appropriate scripts, test setup, lint/typecheck setup, and a README.
+
+## Security and secrets
+- Never hard-code secrets.
+- Never commit mock credentials or insecure defaults.
+- Secrets must only be stored in environment variables or the database, whichever is appropriate for the use case.
+- Prefer secure defaults.