# -----------------------------------------------------------------------------------
# This file defines project standards, conventions, and rules for AI assistants.
# It should be placed at the root of your project as .cursorrules, .windsurfrules,
# or .clinerules. Leave all three symlinks in place for maximum compatibility.
#
# NOTE: The placeholders below (e.g., {{NEXTJS_VERSION}}, {{STYLING_APPROACH}})
# are designed for an LLM to fill in once it has analyzed the project codebase.
# They should not be assumed or hardcoded without confirmation from the source code.
# -----------------------------------------------------------------------------------

metadata:
  version: "1.0.0"
  created_at: "2025-03-31"
  updated_at: "2025-03-31"
  template_type: "project_rules"
  intended_use: "AI IDE project initialization"
  author: "GitMaxd"
  package_url: "https://www.npmjs.com/package/ai-init"

# Schema information to help LLMs understand the structure
schema:
  version: "1.0"
  sections:
    - project
    - documentation
    - conventions
    - testing
    - security
    - architecture
    - workflow
    - maintenance
    - commit_format
    - rules
    - llm_instructions
    - examples
    - template_completion

description: "Next.js Project Configuration and Enforcement Rules (Placeholders for version/technologies)"

# ---------------------------------------------------------------------
# PROJECT INFORMATION - placeholders are used to be filled by the LLM
# ---------------------------------------------------------------------
project:
  name: "{{PROJECT_NAME}}"
  type: "{{PROJECT_TYPE}}"  # e.g., "Next.js application" or "Node.js microservice"
  goal: "{{PROJECT_GOAL}}"
  technologies:
    - "Next.js {{NEXTJS_VERSION}}"  # e.g., Next.js 13, or Next.js 12
    - "React"
    - "TypeScript"
    - "{{ADDITIONAL_TECHNOLOGY_1}}"  # e.g., Tailwind, Redux
    - "{{ADDITIONAL_TECHNOLOGY_2}}"
  features:
    - "{{FEATURE_1}}"
    - "{{FEATURE_2}}"
    - "{{FEATURE_3}}"

# ---------------------------------------------------------------------
# DOCUMENTATION STRUCTURE AND REQUIREMENTS
# ---------------------------------------------------------------------
documentation:
  locations:
    - path: doc-files/
      purpose: General project documentation
    - path: memory-bank/
      purpose: Structured project knowledge
  memory_bank_required_files:
    - projectbrief.md     # High-level project goals and requirements
    - techContext.md      # Technical stack and architectural decisions
    - systemPatterns.md   # Common patterns and conventions
    - activeContext.md    # Current work in progress
    - progress.md         # Project status and milestone tracking

# ---------------------------------------------------------------------
# CODE STYLE AND CONVENTIONS
# ---------------------------------------------------------------------
conventions:
  general:
    - Clear, descriptive variable and function names
    - Comment complex logic
    - Single responsibility functions
    - Limit line length to 80 characters  # Placeholder—may be adjusted after LLM analysis
  javascript_typescript:
    naming:
      variables:
        pattern: "^[a-z][a-zA-Z0-9]*$"
        style: camelCase
        examples: ["userId", "apiResponse"]
      classes:
        pattern: "^[A-Z][a-zA-Z0-9]*$"
        style: PascalCase
        examples: ["UserProfile", "ApiClient"]
      files:
        component:
          pattern: "^[A-Z][a-zA-Z0-9]*\\.(tsx|jsx)$"
          style: PascalCase
          examples: ["Button.tsx", "UserProfile.tsx"]
        utility:
          pattern: "^[a-z][a-z0-9-]*\\.(ts|js)$"
          style: kebab-case
          examples: ["api-helpers.ts", "date-utils.ts"]
        page:
          # For Next.js: The actual pattern depends on whether we're using the App Router or Pages Router.
          # The LLM will confirm the correct pattern by analyzing the codebase.
          pattern: "^([a-z][a-z0-9-]*|\\[\\w+\\]|layout|page|loading|error)\\.tsx$"
          style: "kebab-case for routes, snake_case for dynamic segments, etc."
          examples: ["about-us.tsx", "[product_id].tsx", "page.tsx"]
    practices:
      - Prefer const over let
      - Avoid var
      - Use async/await instead of promise chains
      - "{{SERVER_COMPONENT_GUIDELINE}}"  # e.g., "If using Next.js >=13 with App Router, prefer server components"
      - "{{CLIENT_COMPONENT_GUIDELINE}}"  # e.g., "Use client components if you need browser APIs or user interaction"
      - "{{DATA_FETCHING_GUIDELINE}}"     # e.g., "Prefer server actions for data mutations if supported"
  css_scss:
    naming:
      # This is a placeholder approach; if Tailwind or another CSS framework is in use, the LLM should update accordingly.
      style: BEM
      examples: [".block__element--modifier", ".card__title--highlighted"]
    sort_properties: true
    use_variables:
      - colors
      - spacing

# ---------------------------------------------------------------------
# TESTING REQUIREMENTS
# ---------------------------------------------------------------------
testing:
  required:
    - Unit tests for utilities and services
    - Component tests for UI elements
    - Integration tests for critical user flows
  location: "Colocated with code, .test.ts suffix"
  tools:
    - Jest
    - React Testing Library
    - Playwright  # or Cypress, or any other E2E framework
  coverage:
    minimum: "{{MINIMUM_TEST_COVERAGE}}"  # e.g., 80%

# ---------------------------------------------------------------------
# SECURITY GUIDELINES
# ---------------------------------------------------------------------
security:
  restricted_files:
    - .env
    - .env.*
    - credentials.json
    - "{{ADDITIONAL_SENSITIVE_FILES}}"  # e.g., "firebaseAdminKey.json"
  practices:
    - Never hardcode API keys or credentials
    - Use environment variables for sensitive configuration
    - Sanitize user inputs to prevent injection attacks
    - Follow OWASP security guidelines for web applications
    - If using Next.js middleware for auth, specify approach in memory-bank docs

# ---------------------------------------------------------------------
# ARCHITECTURE INFORMATION
# ---------------------------------------------------------------------
architecture:
  pattern: "{{ARCHITECTURAL_PATTERN}}"  
  # e.g., "Next.js App Router", "Next.js Pages Router", "Hybrid SSG/SSR approach"
  
  state_management: "{{STATE_MANAGEMENT}}" 
  # e.g., "Server Components + React Context", "Redux", "React Query", etc.

  api_communication: "{{API_COMMUNICATION}}"  
  # e.g., "Server Actions", "getServerSideProps", "API Routes"

  routing:
    - "If using App Router (Next.js >=13), place route handlers in app/"
    - "If using Pages Router (Next.js <=12), use pages/ and the standard file-based approach"
  directory_structure:
    - app/ or pages/   # LLM will confirm which one is used in the codebase
    - components/      # Shared UI components
    - lib/             # Core utilities and services
    - public/          # Static assets

# ---------------------------------------------------------------------
# DEVELOPMENT WORKFLOW
# ---------------------------------------------------------------------
workflow:
  process:
    - Create branch per feature/fix
    - Write tests before implementation when possible
    - Run linters and tests before committing
    - Follow conventional commits format
  ci_cd:
    - "{{CI_CD_TOOL}}"  # e.g., GitHub Actions, GitLab CI, Jenkins, etc.
    - "Automate lint/test checks before merge"

# ---------------------------------------------------------------------
# MAINTENANCE PROCEDURES
# ---------------------------------------------------------------------
maintenance:
  update_files:
    - activeContext.md  # Update with current state
    - progress.md       # Update with completed items
    - systemPatterns.md # Update if new patterns emerge
    - techContext.md    # Update if new technologies are introduced
    - projectbrief.md   # Update if project goals change
  dependency_updates:
    - "Use {{DEPENDENCY_UPDATE_TOOL}} to keep dependencies current (e.g., npm audit, Yarn, Dependabot)."

# ---------------------------------------------------------------------
# GIT COMMIT MESSAGE FORMAT
# ---------------------------------------------------------------------
commit_format:
  pattern: "<type>[optional scope]: <description>\n\n[optional body]\n\n[optional footer]"
  types:
    - feat     # New feature
    - fix      # Bug fix
    - docs     # Documentation changes
    - style    # Formatting changes
    - refactor # Code change that neither fixes a bug nor adds a feature
    - perf     # Performance improvements
    - test     # Adding or correcting tests
    - build    # Changes to build process
    - ci       # Changes to CI configuration
    - chore    # Maintenance tasks
    - revert   # Revert previous commit
  guidelines:
    subject: "Imperative, lowercase, no period, ≤50 chars"
    body: "Explain WHY, not HOW, wrap at 72 chars"
    footer: "Use Fixes #123 or BREAKING CHANGE: description"
  examples:
    - "feat(auth): implement SSO functionality"
    - "fix(api): prevent timeout on large requests\n\nIncreased request timeout and implemented streaming response.\nFixes #422"

# ---------------------------------------------------------------------
# RULES FOR ENFORCING PROJECT STANDARDS
# ---------------------------------------------------------------------
rules:
  - name: architecture_alignment
    description: "Ensure new features follow the chosen Next.js conventions (App Router or Pages Router)."
    filters:
      - type: file_extension
        pattern: "\\.(ts|tsx|js|jsx)$"
    actions:
      - type: suggest
        message: "Check doc-files/ or memory-bank for guidance on architectural decisions."

  - id: "rule-001"
    name: "memory_bank_enforcement"
    description: "Memory bank files must exist and follow naming/location conventions"
    severity: "error"
    applies_to: "memory-bank/"
    validation:
      required_files:
        - projectbrief.md
        - techContext.md
        - systemPatterns.md
        - activeContext.md
        - progress.md

  - id: "rule-002"
    name: "nextjs_best_practices"
    description: "Placeholder for Next.js best practices. LLM will confirm version-specific rules."
    severity: "warning"
    applies_to: "app/ or pages/"
    validation:
      file_patterns:
        - pattern: "^page\\.tsx$"
          message: "If using Pages Router, page components should be the default export in page.tsx. If using App Router, confirm the relevant naming convention."
        - pattern: "^layout\\.tsx$"
          message: "If using App Router, layout components should be the default export in layout.tsx."
        - pattern: "^loading\\.tsx$"
          message: "If using App Router, loading components should be the default export in loading.tsx."

# ---------------------------------------------------------------------
# INSTRUCTIONS FOR LLMs ON HOW TO INTERPRET AND APPLY THESE RULES
# ---------------------------------------------------------------------
llm_instructions:
  - "Use these rules to guide code generation and recommendations for a Next.js project."
  - "Fill placeholders like {{NEXTJS_VERSION}} or {{ARCHITECTURAL_PATTERN}} by analyzing the actual codebase."
  - "Do NOT assume a Next.js version unless confirmed by the code (App Router vs. Pages Router)."
  - "Follow naming conventions defined here or in code-level config if conflicts arise."
  - "Suggest corrections when code doesn't follow these standards."
  - "If the project uses Next.js ≥13 with App Router, default to server components when possible."
  - "If the project uses Next.js ≤12 with the Pages Router, use the standard getStaticProps/getServerSideProps/data fetching approach."
  - "Apply coverage thresholds, lint checks, and memory-bank validations as described."