/**
 * Cursor rules for maintaining code quality and consistency
 */

{
  "rules": {
    "file-header-docs": {
      "description": "All source files must have a header comment explaining their purpose",
      "pattern": "src/**/*.js",
      "check": {
        "type": "regex",
        "value": "^/\\*\\*\\n \\* [^\\n]+\\n \\* [^\\n]+\\n \\* [^\\n]+\\n \\*/\\n",
        "message": "File must start with a header comment block (3 lines) explaining its purpose"
      }
    }
  }
}

# Project Principles

# Code Philosophy
- Keep code simple, smart, and follow best practices
- Don't over-engineer for the sake of engineering
- Use standard conventions and patterns
- Write human-readable code
- Keep it simple so the app just works
- Follow the principle: "Make it work, make it right, make it fast"
- Comments should explain "why" behind the code in more complex functions
- Overcommented code is better than undercommented code

# Commit Conventions
- Use Conventional Commits format:
  - feat: new features
  - fix: bug fixes
  - docs: documentation changes
  - style: formatting, missing semi colons, etc.
  - refactor: code changes that neither fix bugs nor add features
  - test: adding or modifying tests
  - chore: updating build tasks, package manager configs, etc.
- Each commit should be atomic and focused
- Write clear, descriptive commit messages

# Project Structure

# Root Directory
- Keep root directory clean with only essential files
- Production configuration files in root:
  - docker-compose.yml
  - Dockerfile
  - .env.example
  - package.json
  - README.md

# Source Code (/src)
- All application source code in /src directory
  - app.js: Application setup and configuration
  - server.js: Server entry point
  - routes/: Route handlers
  - middleware/: Custom middleware
  - utils/: Helper functions and utilities
  - models/: Data models (if applicable)
  - services/: Business logic

# Development
- All development configurations in /dev directory
- Development specific files:
  - /dev/docker-compose.dev.yml
  - /dev/.env.dev.example
  - /dev/README.md (development setup instructions)

# Static Assets and Uploads
- Static assets in /public directory
- Upload directories:
  - /uploads (production)
  - /local_uploads (local development)

# Documentation
- Main README.md in root focuses on production deployment
- Development documentation in /dev/README.md
- Code must be self-documenting with clear naming
- Complex logic must include comments explaining "why" not "what"
- JSDoc comments for public functions and APIs

# Docker Configuration
- Use environment-specific .dockerignore files:
  - .dockerignore: Production defaults (most restrictive)
  - dev/.dockerignore: Development-specific (allows test/dev files)
- Production .dockerignore should exclude:
  - All test files and configurations
  - Development-only dependencies
  - Documentation and non-essential files
  - Local development configurations
- Development .dockerignore should:
  - Allow test files and configurations
  - Allow development dependencies
  - Still exclude node_modules and sensitive files
  - Keep Docker-specific files excluded
- Docker Compose configurations:
  - Production: docker-compose.yml in root
  - Development: docker-compose.dev.yml in /dev
  - Use BuildKit features when needed
  - Document any special build arguments
- Multi-stage builds:
  - Use appropriate base images
  - Minimize final image size
  - Separate development and production stages
  - Use specific version tags for base images

# Code Style
- Follow ESLint and Prettier configurations
- Use meaningful variable and function names
- Keep functions small and focused
- Maximum line length: 100 characters
- Use modern JavaScript features appropriately
- Prefer clarity over cleverness
- Add logging when appropriate and environment variable DEBUG is set to true

# Code Organization and Modularity
- Break complex functionality into separate modules
- Each module should have a single responsibility
- Modules should be self-contained with clear interfaces
- Avoid circular dependencies between modules
- Keep module files under 300 lines when possible
- Export only what is necessary from each module
- Group related functionality in the same directory

# Theme and Styling
- Maintain consistent theme colors across the application:
  - Light theme colors:
    - Background: #ffffff
    - Text: #1a1a1a
    - Primary: #2563eb
    - Secondary: #64748b
  - Dark theme colors:
    - Background: #1a1a1a
    - Text: #ffffff
    - Primary: #3b82f6
    - Secondary: #94a3b8
- Theme toggle must be present on all pages
- Theme preference must persist in localStorage
- System theme preference should be respected by default

# Security and Authentication
- PIN authentication logic in login.html must not be modified without verification and override from the owner
- PIN input fields must:
  - Use type="password"
  - Have numeric validation
  - Support paste functionality
  - Auto-advance on input
  - Support backspace navigation
- Maintain brute force protection with:
  - Maximum attempt limits
  - Lockout periods
  - Constant-time PIN comparison
- Session management must use secure cookies 
