launchr/.cursorrules

#Launchr Rules

Every time you choose to apply a rule(s), explicitly state the rule(s) in the output. You can abbreviate the rule description to a single word or phrase.

# Definição da Stack Tecnológica
tech_stack:
  framework: "React"
  language: "TypeScript"
  styling: 
    framework: "Bootstrap 5"
    preprocessor: "SCSS"
    additional: "custom CSS modules"
  bundler: "Vite"
  testing: "Jest"
  state: "Redux Toolkit"
  api: "Chrome Extension API"
  storage: "Chrome Storage API"
  ai: "OpenAI API"
  ui_libraries:
    - "Bootstrap 5.3.3"
    - "Bootstrap Icons"

## Code Style and Structure
- Write concise, technical TypeScript code with accurate examples
- Use functional and declarative programming patterns; avoid classes
- Prefer iteration and modularization over code duplication
- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError)
- Structure repository files as follows:

# Estrutura de Pastas do Projeto
directory_structure:
  src:
    background:
      desc: "Scripts de background da extensão"
      files: ["index.ts", "services/*.ts"]
      
    content:
      desc: "Scripts que são injetados nas páginas"
      files: 
        - "index.ts"
        - "components/*.tsx"
        - "style.css"
        
    popup:
      desc: "Interface do popup da extensão"
      files:
        - "index.tsx"
        - "Router.tsx"
        - "components/*.tsx"
        
    services:
      desc: "Serviços compartilhados"
      files: ["ai/*.ts", "api/*.ts", "storage/*.ts"]
      
    store:
      desc: "Gerenciamento de estado Redux"
      files: 
        - "index.ts"
        - "slices/*.ts"
        
    utils:
      desc: "Utilitários e helpers"
      files: ["*.ts"]
      
    assets:
      desc: "Recursos estáticos"
      files: ["icons/*", "images/*"]
      
    styles:
      desc: "Estilos globais e Bootstrap customização"
      files: 
        - "custom.scss"
        - "variables.scss"
        - "*.css"
      
    types:
      desc: "Definições de tipos TypeScript"
      files: ["*.d.ts"]
      
  lib:
    desc: "Bibliotecas externas"
    files:
      - "bootstrap.min.css"
      - "bootstrap.bundle.min.js"

# Regras de Segurança
security:
  content_security_policy: true
  permissions:
    required: ["activeTab", "storage", "scripting"]
    optional: ["contextMenus"]
  cors:
    allowed_origins: 
      - "https://launchr.com.br"
      - "https://api.openai.com"
      - "*://www.linkedin.com/*"
  storage:
    encryption: true
    sensitive_data: ["authToken", "userCredentials"]

# Configurações de Teste
testing:
  unit:
    framework: "Jest"
    coverage: 80
    directories: ["__tests__", "**/*.test.ts"]
  e2e:
    framework: "Playwright"
    browsers: ["chrome"]
  patterns:
    test_files: "*.test.ts"
    mock_files: "*.mock.ts"
    snapshot_files: "*.snap"

# Documentação
documentation:
  required_files:
    - "README.md"
    - "CHANGELOG.md"
    - "LICENSE"
  components:
    props_documentation: true
    examples: true
    stories: true
  api:
    swagger: true
    endpoints_documentation: true
  chrome:
    permissions_explanation: true
    installation_guide: true

# Performance
performance:
  bundle_size_limits:
    background: "100KB"
    content: "150KB"
    popup: "200KB"
  lazy_loading: true
  code_splitting: true
  caching:
    strategies: ["network-first", "cache-first"]
  optimization:
    minify: true
    tree_shaking: true

# Gestão de Estado
state_management:
  redux:
    slices_pattern: "^[a-z]+Slice$"
    selectors_pattern: "^select[A-Z][a-zA-Z]+$"
    actions_pattern: "^[a-z]+[A-Z][a-zA-Z]+$"
  storage:
    persistence: true
    sync_strategy: "periodic"

rules:
  background:
    pattern: "^[a-z][a-zA-Z0-9]*$"
    directory: "src/background"
    
  content:
    pattern: "^[a-z][a-zA-Z0-9]*$"
    directory: "src/content"
    
  components:
    pattern: "^[A-Z][a-zA-Z0-9]*$"
    directory: "src/content/components"
    
  styles:
    pattern: "^[a-z][a-zA-Z0-9-]*\.(css|scss)$"
    directory: "src/styles"
    
  assets:
    pattern: "^[a-z0-9-]*\.(png|svg)$"
    directory: "src/assets"

formatting:
  indentation: 2
  max_line_length: 100
  quotes: "single"
  semicolons: true
  
  typescript:
    interface_pattern: "^[A-Z][a-zA-Z0-9]*Props$"
    type_pattern: "^[A-Z][a-zA-Z0-9]*Type$"
    
  css:
    class_naming: "bootstrap-convention"
    bootstrap_classes:
      prefix: ["btn-", "form-", "card-", "nav-", "bg-", "text-"]
    custom_classes:
      prefix: "launchr-"

conventions:
  imports:
    order: ["react", "chrome-api", "bootstrap", "external", "components", "styles"]
    grouping: true
    bootstrap:
      css: "import 'bootstrap/dist/css/bootstrap.min.css'"
      js: "import 'bootstrap/dist/js/bootstrap.bundle.min.js'"
    
  messages:
    pattern: "^[A-Z][A-Z_]*$"
    
  storage:
    keys: "camelCase"

linting:
  chrome:
    manifest_version: 3
    permissions_check: true
    
  typescript:
    strict: true
    no_any: true
    
  react:
    hooks_exhaustive_deps: true
    prefer_functional: true
    
  bootstrap:
    version: "5.3.3"
    required_meta: true
    responsive_meta: true

scripts:
  build:
    command: "npm run build"
    output: "dist"
    
  assets:
    copy:
      - "src/assets/icon*.png"
      - "manifest.json"
      - "*.css"
      - "lib/bootstrap*"



## Naming Conventions
- Use lowercase with dashes for directories (e.g., components/form-wizard)
- Favor named exports for components and utilities
- Use PascalCase for component files (e.g., VisaForm.tsx)
- Use camelCase for utility files (e.g., formValidator.ts)

## TypeScript Usage
- Use TypeScript for all code; prefer interfaces over types
- Avoid enums; use const objects with 'as const' assertion
- Use functional components with TypeScript interfaces
- Define strict types for message passing between different parts of the extension
- Use absolute imports for all files @/...
- Avoid try/catch blocks unless there's good reason to translate or handle error in that abstraction
- Use explicit return types for all functions

## Chrome Extension Specific
- Use Manifest V3 standards
- Implement proper message passing between components:
  ```typescript
  interface MessagePayload {
    type: string;
    data: unknown;
  }
  ```
- Handle permissions properly in manifest.json
- Use chrome.storage.local for persistent data
- Implement proper error boundaries and fallbacks
- Use lib/storage for storage related logic
- For the async injected scripts in content/, 
  - they must not close over variables from the outer scope
  - they must not use imported functions from the outer scope
  - they must have wrapped error handling so the error message is returned to the caller

## State Management
- Use React Context for global state when needed
- Implement proper state persistence using chrome.storage (for extension)
- Implement proper cleanup in useEffect hooks

## Syntax and Formatting
- Use "function" keyword for pure functions
- Avoid unnecessary curly braces in conditionals
- Use declarative JSX
- Implement proper TypeScript discriminated unions for message types

## UI and Styling
- Implement Bootstrap 5 for styling
- Consider extension-specific constraints (popup dimensions, permissions)
- Follow Material Design guidelines for Chrome extensions

## Error Handling
- Implement proper error boundaries
- Log errors appropriately for debugging
- Provide user-friendly error messages
- Handle network failures gracefully

## Testing
- Write unit tests for utilities and components
- Implement E2E tests for critical flows
- Test across different Chrome versions
- Test memory usage and performance

## Security
- Implement Content Security Policy
- Sanitize user inputs
- Handle sensitive data properly
- Follow Chrome extension security best practices
- Implement proper CORS handling

## Git Usage
Commit Message Prefixes:
- "fix:" for bug fixes
- "feat:" for new features
- "perf:" for performance improvements
- "docs:" for documentation changes
- "style:" for formatting changes
- "refactor:" for code refactoring
- "test:" for adding missing tests
- "chore:" for maintenance tasks

Rules:
- Use lowercase for commit messages
- Keep the summary line concise
- Include description for non-obvious changes
- Reference issue numbers when applicable

## Documentation
- Maintain clear README with setup instructions
- Document API interactions and data flows
- Keep manifest.json well-documented
- Don't include comments unless it's for complex logic
- Document permission requirements

## Development Workflow
- Use proper version control
- Implement proper code review process
- Test in multiple environments
- Follow semantic versioning for releases
- Maintain changelog