Exchange Creation, Events Enhancements, i18n & Docs/CI Upgrades

.github/copilot-instructions.md

@@ -4,14 +4,16 @@ This repository contains the **Better Together Community Engine** (an isolated R
 
 ## Core Principles
 
+- **Security first**: Run `bundle exec brakeman --quiet --no-pager` before generating code; fix high-confidence vulnerabilities
 - **Accessibility first** (WCAG AA/AAA): semantic HTML, ARIA roles, keyboard nav, proper contrast.
 - **Hotwire everywhere**: Turbo for navigation/updates; Stimulus controllers for interactivity.
 - **Keep controllers thin**; move business logic to POROs/service objects or concerns.
 - **Prefer explicit join models** over polymorphic associations when validation matters.
-- **Avoid the term “STI”** in code/comments; use “single-table inheritance” or alternate designs.
+- **Avoid the term "STI"** in code/comments; use "single-table inheritance" or alternate designs.
 - **Use `ENV.fetch`** rather than `ENV[]`.
 - **Always add policy/authorization checks** on links/buttons to controller actions.
 - **i18n & Mobility**: every user-facing string must be translatable; include missing keys.
+- Provide translations for all available locales (e.g., en, es, fr) when adding new strings.
 
 ## Technology Stack
 
@@ -34,9 +36,38 @@ This repository contains the **Better Together Community Engine** (an isolated R
 
 > Dev DB: PostgreSQL (not SQLite). Production: PostgreSQL. PostGIS enabled for geospatial needs.
 
+## Documentation & Diagrams Policy
+
+- For any new functionality, routes, background jobs, or changes to models/associations:
+  - Update or add documentation under `docs/` describing the behavior and flows.
+  - Maintain Mermaid diagrams (`.mmd`) reflecting new or changed relationships and process flows.
+  - Regenerate PNGs from `.mmd` sources using `bin/render_diagrams`.
+- Ensure PRs include docs/diagrams updates when applicable; missing updates should be treated as a review blocker.
+- When modifying exchange (Joatu) features (Offers, Requests, Agreements, Notifications), keep both the process doc and flow diagram in sync.
+
 
 ## Coding Guidelines
 
+### Security Requirements
+- **Run Brakeman before generating code**: `bundle exec brakeman --quiet --no-pager` 
+- **Fix high-confidence vulnerabilities immediately** - never ignore security warnings with "High" confidence
+- **Review and address medium-confidence warnings** that are security-relevant
+- **Safe coding practices when generating code:**
+  - **No unsafe reflection**: Never use `constantize`, `safe_constantize`, or `eval` on user input
+  - **Use allow-lists for dynamic class resolution**: Follow the `joatu_source_class` pattern with concern-based allow-lists
+  - **Validate user inputs**: Always sanitize and validate parameters, especially for file uploads and dynamic queries
+  - **Strong parameters**: Use Rails strong parameters in all controllers
+  - **Authorization everywhere**: Implement Pundit policy checks on all actions
+  - **SQL injection prevention**: Use parameterized queries, avoid string interpolation in SQL
+  - **XSS prevention**: Use Rails auto-escaping, sanitize HTML inputs with allowlists
+- **For reflection-based features**: Create concerns with `included_in_models` class methods for safe dynamic class resolution
+- **Post-generation security check**: Run `bundle exec brakeman --quiet --no-pager -c UnsafeReflection,SQL,CrossSiteScripting` after major code changes
+
+## Test Environment Setup
+- Configure the host Platform in a before block for controller/request/feature tests.
+  - Create/set a Platform as host (with community) before requests.
+  - Toggle requires_invitation and provide invitation_code when needed.
+
 - **Ruby/Rails**
   - 2-space indent, snake_case methods, Rails conventions
   - Service objects in `app/services/`
@@ -48,24 +79,90 @@ This repository contains the **Better Together Community Engine** (an isolated R
   - Bootstrap utility classes; respect prefers-reduced-motion & other a11y prefs
   - Avoid inline JS; use Stimulus
   - External links in `.trix-content` get FA external-link icon unless internal/mailto/tel/pdf
+  - All user-facing copy must use t("...") and include keys across all locales (add to config/locales/en.yml, es.yml, fr.yml).
 - **Hotwire**
   - Use Turbo Streams for CRUD updates
   - Stimulus controllers in `app/javascript/controllers/`
   - No direct DOM manipulation without Stimulus targets/actions
 - **Background Jobs**
   - Sidekiq jobs under appropriate queues (`:default`, `:mailers`, `:metrics`, etc.)
   - Idempotent job design; handle retries
+  - When generating emails/notifications, localize both subject and body for all locales.
 - **Search**
   - Update `as_indexed_json` to include translated/plain-text fields as needed
 - **Encryption & Privacy**
   - Use AR encryption for sensitive columns
   - Ensure blobs are encrypted at rest
 - **Testing**
   - RSpec (if present) or Minitest – follow existing test framework
+  - **Generate comprehensive test coverage for all changes**: Every modification must include RSpec tests covering the new functionality
   - All RSpec specs **must use FactoryBot factories** for model instances (do not use `Model.create` or `Model.new` directly in specs).
   - **A FactoryBot factory must exist for every model**. When generating a new model, also generate a factory for it.
   - **Factories must use the Faker gem** to provide realistic, varied test data for all attributes (e.g., names, emails, addresses, etc.).
+  - **Test all layers**: models, controllers, mailers, jobs, JavaScript/Stimulus controllers, and integration workflows
   - System tests for Turbo flows where possible
+  - **Session-based testing**: When working on existing code modifications, generate tests that cover all unstaged changes and related functionality
+
+## Test Generation Strategy
+
+### Mandatory Test Creation
+When modifying existing code or adding new features, always generate RSpec tests that provide comprehensive coverage:
+
+1. **Model Tests**: 
+   - Validations, associations, scopes, callbacks
+   - Instance methods, class methods, delegations
+   - Business logic and calculated attributes
+   - Security-related functionality (encryption, authorization)
+
+2. **Controller Tests**:
+   - All CRUD actions and custom endpoints
+   - Authorization policy checks (Pundit/equivalent)
+   - Parameter handling and strong params
+   - Response formats (HTML, JSON, Turbo Stream)
+   - Error handling and edge cases
+
+3. **Background Job Tests**:
+   - Job execution and success scenarios
+   - Retry logic and error handling
+   - Side effects and state changes
+   - Queue assignment and timing
+
+4. **Mailer Tests**:
+   - Email content and formatting
+   - Recipient handling and localization
+   - Attachment and delivery configurations
+   - Multi-locale support
+
+5. **JavaScript/Stimulus Tests**:
+   - Controller initialization and teardown
+   - User interaction handlers
+   - Form state management and dynamic updates
+   - Target and action mappings
+
+6. **Integration Tests**:
+   - Complete user workflows
+   - Cross-model interactions
+   - End-to-end feature functionality
+   - Authentication and authorization flows
+
+### Session-Specific Test Coverage
+For this codebase, ensure tests cover all recent changes including:
+- Enhanced LocatableLocation model with polymorphic associations
+- Event model with notification callbacks and location integration
+- Calendar and CalendarEntry associations
+- Event notification system (EventReminderNotifier, EventUpdateNotifier)
+- Background jobs for event reminders and scheduling
+- EventMailer with localized content
+- Dynamic location selector JavaScript controller
+- Form enhancements with location type selection
+
+### Test Quality Standards
+- Use descriptive test names that explain the expected behavior
+- Follow AAA pattern (Arrange, Act, Assert) in test structure
+- Mock external dependencies and network calls
+- Test both success and failure scenarios
+- Use shared examples for common behavior patterns
+- Ensure tests are deterministic and can run independently
 
 ## Project Architecture Notes
 
@@ -94,3 +191,13 @@ This repository contains the **Better Together Community Engine** (an isolated R
 ---
 
 _If you generate code that touches any of these areas, consult the relevant instruction file and follow it._
+
+## Internationalization & Translation Normalization
+- Use the `i18n-tasks` gem to:
+  - Normalize locale files (`i18n-tasks normalize`).
+  - Identify and add missing keys (`i18n-tasks missing`, `i18n-tasks add-missing`).
+  - Ensure all user-facing strings are present in all supported locales (en, fr, es, etc.).
+  - Add new keys in English first, then translate.
+  - Review translation health regularly (`i18n-tasks health`).
+- All new/changed strings must be checked with `i18n-tasks` before merging.
+- See `.github/instructions/i18n-mobility.instructions.md` for details.

.github/pull_request_template.md

@@ -0,0 +1,21 @@
+## Summary
+
+Describe the change and the motivation.
+
+## Checklist
+
+- [ ] Tests added/updated and passing (`bin/ci`).
+- [ ] Lint and security checks (`rubocop`, `brakeman`, `bundler-audit`).
+- [ ] Documentation updated under `docs/` describing new/changed functionality.
+- [ ] Mermaid diagrams (`docs/*.mmd`) updated to reflect changes.
+- [ ] Rendered PNGs regenerated with `bin/render_diagrams` and committed.
+- [ ] For DB changes, included any needed backfills/dedupes and noted risks.
+
+## Screenshots / Diagrams
+
+If applicable, include screenshots or link to updated diagrams.
+
+## Notes
+
+Anything reviewers should be aware of (migration order, flags, feature toggles).
+

.github/workflows/diagrams.yml

@@ -0,0 +1,34 @@
+name: Diagrams Check
+
+on:
+  pull_request:
+    branches: [ "**" ]
+
+jobs:
+  render-and-verify:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Render Mermaid diagrams
+        run: |
+          chmod +x bin/render_diagrams || true
+          ./bin/render_diagrams || true
+
+      - name: Verify rendered PNGs are up to date
+        run: |
+          CHANGED=$(git status --porcelain -- docs/*.png | wc -l)
+          if [ "$CHANGED" -gt 0 ]; then
+            echo "Diagrams PNGs are out of date. Please run bin/render_diagrams and commit the updated PNGs." >&2
+            echo "Changed files:" >&2
+            git status --porcelain -- docs/*.png >&2 || true
+            exit 1
+          fi
+        shell: bash
+

.github/workflows/i18n-health.yml

@@ -0,0 +1,48 @@
+name: i18n Translation Health Report
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+  pull_request:
+    branches:
+      - main
+      - dev
+
+jobs:
+  i18n-health:
+    runs-on: ubuntu-latest
+    env:
+      # Ensure dev/test gems (incl. i18n-tasks) are installed
+      BUNDLE_WITHOUT: ""
+      BUNDLE_WITH: "development:test"
+    if: github.event_name == 'push' || github.event_name == 'pull_request'
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        env:
+          # Ensure bundler installs dev/test groups during caching step
+          BUNDLE_WITHOUT: ""
+          BUNDLE_WITH: "development:test"
+        with:
+          ruby-version: '3.4.4'
+          bundler-cache: true
+      - name: Verify i18n-tasks
+        run: bundle exec i18n-tasks --version
+      - name: Normalize locale files
+        run: bin/i18n normalize
+      - name: Run i18n checks
+        run: bin/i18n check
+      - name: Upload i18n health report
+        if: always()
+        run: bin/i18n health > i18n-health.txt
+        continue-on-error: true
+      - name: Archive i18n health report
+        uses: actions/upload-artifact@v4
+        with:
+          name: i18n-health-report
+          path: i18n-health.txt
+    continue-on-error: true

.github/workflows/rubyonrails.yml

@@ -87,6 +87,7 @@ jobs:
           echo "Waiting for Elasticsearch to be healthy..."
           curl -s "http://localhost:9200/_cluster/health?wait_for_status=yellow&timeout=60s" || (echo "Elasticsearch not healthy" && exit 1)
 
+
       - name: Run RSpec
         if: (matrix.rails == '7.1.5.2') || steps.update.outcome == 'success'
         env:
@@ -96,6 +97,14 @@ jobs:
           bundle exec rspec
         continue-on-error: ${{ matrix.allowed_failure }}
 
+      - name: Upload coverage report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report-ruby-${{ matrix.ruby }}-rails-${{ matrix.rails }}
+          path: |
+            coverage/
+
       - name: Generate coverage badge
         if: ${{ github.ref == 'refs/heads/main' && success() }}
         continue-on-error: true