jonesrussell godo .cursorrules file for Go (stars: 1)

# .cursorrules file for Godo - A Todo Application with Quick-Note Support

code_style:
- description: "Follow standard Go formatting guidelines and project-specific patterns"
- formatter: gofmt
- rules:
  # Core Code Organization
  - use_platform_specific_build_tags: "Use //go:build for platform-specific code"
  - follow_dependency_injection_pattern: "Use wire for DI, avoid global state"
  - implement_interface_segregation: "Keep interfaces small and focused (max 5 methods)"
  - use_options_pattern: "Use functional options for configurable components"
  - follow_error_handling_conventions: "Use custom error types, wrap errors with context, log before return"
  - follow_interface_naming: "Interface names should end with 'er' or 'Service'"
  - define_interfaces_in_consumer_packages: "Interfaces belong in the package that uses them"

  # Architecture Rules
  - follow_clean_architecture:
    - keep_business_logic_in_internal: "Core business logic belongs in internal/"
    - use_interface_abstractions: "Define interfaces in consumer packages"
    - separate_platform_specific_code: "Use separate files with build tags"
    - follow_dependency_rule: "Dependencies point inward"
    - avoid_central_interfaces_package: "Don't create a central interfaces package"

  # Error Handling Rules
  - error_handling:
    - wrap_errors: "Always wrap errors with context using fmt.Errorf with %w"
    - log_before_return: "Log errors before returning them"
    - use_custom_error_types: "Define domain-specific error types"
    - include_error_context: "Include relevant context in error messages"
    - validate_error_handling: "Ensure all error paths are handled"

  # Interface Design Rules
  - interface_design:
    - max_methods: "Maximum 5 methods per interface"
    - follow_isp: "Split interfaces based on client needs"
    - proper_naming: "Use 'er' suffix for interfaces (e.g., Reader, Writer)"
    - consumer_defined: "Define interfaces where they are used"
    - document_contracts: "Document interface contracts clearly"

  # Testing Rules
  - write_focused_unit_tests: "Each test verifies one specific behavior"
  - use_table_driven_tests: "Use table-driven tests for multiple cases"
  - mock_external_dependencies: "Use interfaces and mocks for external services"
  - test_error_paths: "Test error conditions and edge cases"
  - maintain_test_coverage: "Keep >70% coverage for critical paths"
  - use_testify_suite: "Use testify/suite for organized tests"
  - use_gomock: "Use gomock for interface mocking"
  - test_cleanup_paths: "Test resource cleanup and shutdown"
  - test_lifecycle_management: "Test component lifecycle thoroughly"
  - verify_error_messages: "Verify error message contents"
  - test_platform_specific: "Test platform-specific features separately"
  - test_concurrent_operations: "Test concurrent access and race conditions"
  - test_resource_leaks: "Test for memory and resource leaks"
  - test_error_recovery: "Test system recovery from errors"
  - test_invalid_states: "Test handling of invalid state transitions"
  - test_utilities:
    - use_test_fixtures: "Use TestFixture for common test dependencies"
    - implement_mock_interfaces: "Provide mock implementations for interfaces"
    - provide_helper_functions: "Create reusable test helper functions"
    - handle_async_operations: "Use timeouts and wait functions for async tests"
    - thread_safe_mocks: "Ensure mock implementations are thread-safe"
    - cleanup_resources: "Use t.Cleanup for automatic resource cleanup"
    - context_management: "Provide test context with appropriate timeouts"
  - test_patterns:
    - window_state_tracking: "Track and verify window visibility states"
    - task_assertions: "Verify task existence and properties"
    - log_assertions: "Verify log messages and levels"
    - config_management: "Provide test configurations"
    - store_operations: "Test CRUD operations with mock store"
    - mock_expectations: "Set up and verify mock expectations"
  - test_data:
    - use_test_factories: "Provide functions to create test data"
    - realistic_test_data: "Use realistic data in tests"
    - data_cleanup: "Clean up test data after tests"
    - data_isolation: "Ensure test data doesn't interfere between tests"
  - test_organization:
    - package_level_utilities: "Keep test utilities in testutil package"
    - reusable_components: "Create reusable test components"
    - consistent_patterns: "Follow consistent testing patterns"
    - clear_test_names: "Use descriptive test names"

  # UI Rules
  - follow_fyne_patterns:
    - use_theme_variables: "Use theme variables for consistent styling"
    - handle_window_lifecycle: "Proper window creation and cleanup"
    - manage_input_focus: "Handle focus properly in UI components"
    - implement_proper_layouts: "Use appropriate Fyne layouts"
  - implement_platform_specific_ui:
    - handle_windows_specifics: "Support Windows-specific UI features"
    - handle_linux_specifics: "Support Linux-specific UI features"

  # Storage Rules
  - follow_repository_pattern: "Use repository pattern for data access"
  - use_transactions: "Use transactions for multi-step operations"
  - validate_data: "Validate data before storage operations"
  - handle_migrations: "Support proper database migrations"
  - implement_proper_cleanup: "Clean up resources in Close methods"

  # API Rules
  - follow_rest_conventions: "Use proper HTTP methods and status codes"
  - implement_versioning: "Version API endpoints properly"
  - validate_requests: "Validate all incoming requests"
  - use_middleware: "Use middleware for cross-cutting concerns"
  - handle_websocket_properly: "Proper WebSocket connection management"
  - api_server_lifecycle:
    - start_in_background: "Start API server in a goroutine"
    - graceful_shutdown: "Implement graceful shutdown with context"
    - handle_startup_errors: "Log and handle server startup errors"
    - cleanup_resources: "Clean up resources in correct order"
  - api_server_configuration:
    - configurable_port: "Port should be configurable via config"
    - timeout_settings: "Configure appropriate timeout settings"
    - cors_settings: "Configure CORS for cross-origin requests"
    - rate_limiting: "Configure rate limiting per endpoint"
  - api_server_integration:
    - wire_dependency_injection: "Use wire for API server DI"
    - app_lifecycle_management: "Proper integration with app lifecycle"
    - error_propagation: "Proper error handling and propagation"

  # Logging Rules
  - use_structured_logging: "Use zap for structured logging"
  - log_appropriate_levels: "Use correct log levels"
  - include_context: "Include relevant context in logs"
  - avoid_sensitive_data: "Never log sensitive information"
  - implement_log_rotation: "Support log rotation"

  # Configuration Rules
  - use_yaml_config: "Use YAML for configuration files"
  - validate_config: "Validate configuration at startup"
  - support_env_override: "Allow environment variable overrides"
  - handle_defaults: "Provide sensible defaults"
  - http_configuration:
    - port_configuration: "Configure HTTP server port"
    - timeout_configuration: "Configure server timeouts"
    - cors_configuration: "Configure CORS settings"
    - rate_limit_configuration: "Configure rate limiting"
  - api_configuration:
    - version_configuration: "Configure API version"
    - endpoint_configuration: "Configure API endpoints"
    - auth_configuration: "Configure authentication settings"
    - middleware_configuration: "Configure middleware chain"

  # Build and Distribution Rules
  - use_proper_build_tags: "Use build tags for platform-specific code"
  - support_cross_compilation: "Support building for multiple platforms"
  - manage_dependencies: "Use go modules properly"
  - optimize_binary_size: "Optimize final binary size"

  # Security Rules
  - secure_sensitive_data: "Properly handle sensitive information"
  - use_proper_permissions: "Set correct file permissions"
  - validate_user_input: "Validate all user input"
  - implement_rate_limiting: "Rate limit API endpoints"

  # Performance Rules
  - optimize_hot_paths: "Optimize frequently executed code"
  - use_connection_pooling: "Pool database connections"
  - implement_caching: "Cache expensive operations"
  - profile_performance: "Profile and optimize critical paths"

snippets:
- fyne_keyboard_shortcuts:
    description: "Add keyboard shortcuts using Fyne."
    code: |
      // Add keyboard shortcut (e.g., Ctrl+Enter)
      window.Canvas().AddShortcut(&desktop.CustomShortcut{
          KeyName:  fyne.KeyReturn,  // Or other key like KeyEscape
          Modifier: fyne.KeyModifierControl,  // Optional, remove for no modifier
      }, func(shortcut fyne.Shortcut) {
          // Shortcut handler code here
      })

- fyne_window_setup:
    description: "Set up a Fyne window with basic properties."
    code: |
      // Basic window setup
      win := fyne.CurrentApp().NewWindow("Window Title")
      win.Resize(fyne.NewSize(400, 300))
      win.CenterOnScreen()

      // Add close interceptor
      win.SetCloseIntercept(func() {
          // Cleanup code here
          win.Hide()
      })

      // Focus an input field
      if input != nil {
          win.Canvas().Focus(input)
      })

- fyne_layout_containers:
    description: "Create Fyne layout containers."
    code: |
      // Border layout with margins
      content := container.NewBorder(
          top,    // top widget
          bottom, // bottom widget
          left,   // left widget
          right,  // right widget
          center  // center/main widget
      )

      // Vertical box layout
      content := container.NewVBox(
          widget1,
          widget2,
          widget3,
      )

      // Horizontal box layout
      content := container.NewHBox(
          widget1,
          widget2,
          widget3,
      )

gui_library_notes:
- fyne_io_fyne_v2_5_3:
    description: "Important notes on Fyne.io/fyne v2.5.3 usage."
    notes:
    - key_events_and_shortcuts:
      - key_modifier_does_not_exist: true
      - use_desktop_custom_shortcut: true
      - register_shortcuts_via_canvas: true
      - use_keyname_instead_of_key: true
      - prefer_fyne_key_modifier_control: true
      - debug_key_events_with_extended_widget_entry: true
    - focus_and_window_management:
      - no_request_focus_method: true
      - use_canvas_focus_instead: true
      - call_center_on_screen_after_show: true
      - defer_window_close_in_tests: true
      - set_focus_for_popup_windows_in_show: true
      - set_focus_for_modal_windows_after_content_set: true
    - widget_implementation:
      - call_extend_base_widget_in_constructors: true
      - override_keydown_and_typedkey_for_key_handling: true
      - handle_task_list_updates_correctly: true
      - prefer_composition_over_inheritance_for_widgets: true
    - forms_and_dialogs:
      - set_dialog_size_after_creation: true
      - use_custom_widgets_in_forms: true
      - use_dialog_show_error_for_failures: true
      - show_confirm_for_destructive_actions: true
      - focus_ok_button_in_error_dialogs: true
    - testing_best_practices:
      - use_test_new_app_instead_of_custom_mocks: true
      - use_test_new_window_with_defer_close: true
      - use_test_assert_renders_to_image_for_visual_tests: true
      - use_httptest_new_server_for_http_tests: true
      - use_assert_jsoneq_for_json_comparisons: true
      - clean_up_resources_with_defer: true
      - test_success_and_error_paths: true
      - test_edge_cases_explicitly: true
    - resource_management:
      - use_go_embed_for_test_resources: true
      - clean_up_files_with_defer_os_remove: true
      - handle_windows_path_separators: true
      - use_storage_parse_uri_for_uris: true
    - state_management:
      - use_channels_for_async_notifications: true
      - verify_state_transitions_explicitly: true
      - handle_task_state_in_store_before_ui: true
    - canvas_and_rendering:
      - use_software_new_canvas_for_driver_tests: true
      - test_with_different_scale_factors: true
      - test_with_different_theme_variants: true
      - test_with_different_window_sizes: true
      - compare_rgba_values_exactly: true
      - test_transparent_backgrounds: true
    - error_handling:
      - test_not_implemented_errors: true
      - show_user_friendly_error_messages: true
      - log_detailed_error_information: true
      - handle_network_timeouts: true

project_overview:
- todo_application_features:
    description: "Main features of the Todo application (Cross-platform)."
    features:
    - quick_note_capture_via_global_hotkey: true
    - full_featured_todo_management_interface: true
    - built_with_go_and_sqlite: true
    - current_platforms: [ "Windows", "Linux" ]
    - future_platforms: [ "macOS" ]
    - cross_platform_build_system: true
    - github_actions_ci_cd: true
    - docker_support: true

core_features:
- quick_note_system:
    description: "Features of the Quick-Note system (Windows implementation)."
    features:
    - global_hotkey_registration: true
    - minimal_graphical_popup_window: true
    - platform_specific_implementations: true
    - current_platform: "Windows"
- main_application_window:
    description: "Features of the main application window."
    features:
    - task_organization: true
    - task_completion_tracking: true
    - task_deletion: true
    - modern_graphical_interface_using_fyne_widgets: true

database:
- sqlite3_storage:
    description: "Using SQLite3 for storage."
    features:
    - repository_pattern: true
    - service_layer_abstraction: true

technical_requirements:
- go_version: "1.23 or higher"
- sqlite3: true
- mingw_w64_gcc_for_windows: true
- windows_sdk: true
- task_runner_for_build_automation: true
- jwt_authentication: true
- openapi_swagger: true
- websocket_support: true
- cors_enabled: true
- rate_limiting: true
- api_versioning: true
- secure_headers: true
- performance_monitoring: true

testing_requirements:
- unit_tests_for_all_packages: true
- integration_tests: true
- websocket_connection_tests: true
- authentication_tests: true
- load_performance_tests: true
- ci_pipeline_integration: true

system_integration:
- graceful_shutdown_handling: true
- system_service_support: [ "Windows service" ]
- future_system_service_support: [ "Linux systemd" ]
- auto_start_capability: "Windows Task Scheduler"
- update_mechanism: "Windows-specific"

documentation:
- comprehensive_readme: true
- api_documentation: true
- usage_examples: true
- installation_guides: true
- hotkey_documentation: true
- openapi_specification: true
- configuration_documentation: true

future_considerations:
- task_categories_tags: true
- due_dates_and_reminders: true
- data_export_import: true
- task_priorities: true
- recurring_tasks: true
- multiple_lists: true
- cloud_sync: true

api_features:
- http_server:
    description: "HTTP API server features"
    features:
    - restful_endpoints: true
    - jwt_authentication: true
    - request_validation: true
    - proper_error_handling: true
    - openapi_documentation: true
    - rate_limiting: true
    - cors_support: true
    - graceful_shutdown: true
    - background_operation: true
    - lifecycle_management: true
    - dependency_injection: true
    - configurable_timeouts: true
    - error_logging: true
    - request_logging: true
    - metrics_support: true
- websocket:
    description: "WebSocket features"
    features:
    - real_time_updates: true
    - connection_management: true
    - heartbeat_mechanism: true
    - task_notifications: true
    - error_handling: true
    - reconnection_support: true
    - message_validation: true
    - connection_pooling: true

endpoints:
- get_tasks: "/api/v1/tasks"
- get_task_by_id: "/api/v1/tasks/:id"
- create_task: "/api/v1/tasks"
- update_task: "/api/v1/tasks/:id"
- patch_task: "/api/v1/tasks/:id"
- delete_task: "/api/v1/tasks/:id"
- list_tags: "/api/v1/tags"
- health_check: "/api/v1/health"
- metrics: "/api/v1/metrics"

configuration:
- http_server:
    port: 8080
    read_timeout: 30s
    write_timeout: 30s
    read_header_timeout: 10s
    idle_timeout: 120s
- websocket_settings:
    ping_interval: 30s
    pong_wait: 60s
    write_wait: 10s
    max_message_size: 512
- authentication_settings:
    jwt_secret: "env:JWT_SECRET"
    token_expiration: 24h
    refresh_token_expiration: 7d
- cors_configuration:
    allowed_origins: [ "*" ]
    allowed_methods: [ "GET", "POST", "PUT", "PATCH", "DELETE" ]
    allowed_headers: [ "Content-Type", "Authorization" ]
    max_age: 86400
- rate_limiting:
    requests_per_second: 10
    burst: 20

error_handling:
- use_standard_http_status_codes: true
- provide_meaningful_error_messages: true
- log_errors_with_context: true
- return_consistent_error_responses: true
- include_request_id: true
- sanitize_error_messages: true
- handle_validation_errors: true
- handle_database_errors: true
- handle_timeout_errors: true
- handle_auth_errors: true