Add Agreements and Agreement Terms (#884)

## Pull Request #884: Add Agreements and Agreement Terms

### Overview
- Base branch: main
- Feature branch: feature/agreements
- Commits: 38 commits (from May to August 2025)
- File changes: 238 files changed (+3644 / -2463)

### Key Highlights by File

1. app/builders/better_together/agreement_builder.rb
   - Introduces a seeding builder for default agreements:
     - Privacy Policy
     - Terms of Service
     - Code of Conduct
   - Sets default titles, descriptions, and privacy settings.
   - Includes linking to existing pages if available.

2. app/controllers/better_together/agreements_controller.rb
- New AgreementsController (inherits from FriendlyResourceController).
   - Handles show action:
     - If @agreement.page exists, renders within the appropriate layout.
     - Supports Turbo Frame responses for modal display.

3. app/controllers/better_together/users/registrations_controller.rb
   - Adds flows for agreement acceptance during user signup:
- set_required_agreements to load required Agreement records
(privacy_policy, terms_of_service, and optionally code_of_conduct).
     - Validates checkbox acceptance in agreements_accepted?.
- Creates AgreementParticipant records upon successful signup to track
acceptance.

4. Styling & Layout
- Adds CSS classes in app/assets/stylesheets/better_together/forms.scss
for agreement modals and spacing (e.g., .agreement-modal-link,
.bt-mb-3).

5. Helper Module
- Adds an empty helper module BetterTogether::AgreementsHelper for
future use.

### Summary
This PR lays the groundwork for a structured agreements system:
- Seeds default agreements for users to consent to during signup.
- Renders agreements via modals using Turbo Frames for smooth UX.
- Tracks agreement acceptance per user via AgreementParticipant records.

### Next Steps / Considerations
- Review and refine acceptance flows and error messaging UX.
- Confirm localization support and styling for agreement modals.
- Ensure existing migrations (e.g., agreement_participants) are applied
without conflict.

Author: rsmithlal

.rubocop.yml

@@ -5,6 +5,20 @@ AllCops:
     - 'spec/dummy/db/schema.rb'
     - 'vendor/**/*'
   NewCops: enable
+  TargetRubyVersion: 3.4
+plugins:
+  - rubocop-rails
+  - rubocop-rspec
+  - rubocop-rspec_rails
+  - rubocop-capybara
+  - rubocop-factory_bot
 Style/StringLiterals:
   Exclude:
     - 'db/migrate/*'
+
+Rails:
+  Enabled: false
+Capybara:
+  Enabled: false
+FactoryBot:
+  Enabled: false

app/assets/stylesheets/better_together/forms.scss

@@ -9,6 +9,10 @@
   font-weight: 500;
 }
 
+.agreement-modal-link {
+  text-decoration: none;
+}
+
 .bt-mb-3 {
   margin-bottom: 1rem;
 }

app/builders/better_together/agreement_builder.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# app/builders/better_together/agreement_builder.rb
+
+module BetterTogether
+  # Builder to seed initial agreements
+  class AgreementBuilder < Builder
+    class << self
+      def seed_data
+        build_privacy_policy
+        build_terms_of_service
+        build_code_of_conduct
+      end
+
+      def clear_existing
+        BetterTogether::AgreementParticipant.delete_all
+        BetterTogether::AgreementTerm.delete_all
+        BetterTogether::Agreement.delete_all
+      end
+
+      # rubocop:todo Metrics/AbcSize
+      def build_privacy_policy # rubocop:todo Metrics/MethodLength, Metrics/AbcSize
+        agreement = BetterTogether::Agreement.find_or_create_by!(identifier: 'privacy_policy') do |a|
+          a.protected = true
+          a.title = 'Privacy Policy'
+          a.description = 'Summary of how we handle your data.'
+          a.privacy = 'public'
+        end
+
+        agreement.agreement_terms.find_or_create_by!(identifier: 'privacy_policy_summary') do |term|
+          term.protected = true
+          term.position = 1
+          term.content = 'We respect your privacy and protect your personal information.'
+        end
+
+        # If a Page exists for the privacy policy, link it so the page content
+        # is shown to users instead of the agreement terms.
+        page = BetterTogether::Page.find_by(identifier: 'privacy_policy') ||
+               BetterTogether::Page.find_by(slug: 'privacy-policy')
+        agreement.update!(page: page) if page.present?
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      # rubocop:todo Metrics/AbcSize
+      def build_terms_of_service # rubocop:todo Metrics/MethodLength, Metrics/AbcSize
+        agreement = BetterTogether::Agreement.find_or_create_by!(identifier: 'terms_of_service') do |a|
+          a.protected = true
+          a.title = 'Terms of Service'
+          a.description = 'Rules you agree to when using the platform.'
+          a.privacy = 'public'
+        end
+
+        agreement.agreement_terms.find_or_create_by!(identifier: 'terms_of_service_summary') do |term|
+          term.protected = true
+          term.position = 1
+          term.content = 'Use the platform responsibly and respectfully.'
+        end
+
+        # Link a Terms of Service Page if one exists
+        page = BetterTogether::Page.find_by(identifier: 'terms_of_service') ||
+               BetterTogether::Page.find_by(slug: 'terms-of-service')
+        agreement.update!(page: page) if page.present?
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      # rubocop:todo Metrics/MethodLength
+      def build_code_of_conduct # rubocop:todo Metrics/AbcSize, Metrics/MethodLength
+        agreement = BetterTogether::Agreement.find_or_create_by!(identifier: 'code_of_conduct') do |a|
+          a.protected = true
+          a.title = 'Code of Conduct'
+          a.description = 'Community code of conduct and expectations.'
+          a.privacy = 'public'
+        end
+
+        agreement.agreement_terms.find_or_create_by!(identifier: 'code_of_conduct_summary') do |term|
+          term.protected = true
+          term.position = 1
+          term.content = 'Be respectful, inclusive, and considerate to other community members.'
+        end
+
+        # Link a Code of Conduct Page if one exists
+        page = BetterTogether::Page.find_by(identifier: 'code_of_conduct') ||
+               BetterTogether::Page.find_by(slug: 'code-of-conduct')
+        agreement.update!(page: page) if page.present?
+      end
+      # rubocop:enable Metrics/MethodLength
+    end
+  end
+end

app/controllers/better_together/agreements_controller.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module BetterTogether
+  # CRUD for Agreements
+  class AgreementsController < FriendlyResourceController
+    skip_before_action :check_platform_privacy, only: :show
+
+    # When the agreement is requested inside a Turbo Frame (from the modal),
+    # return only the fragment wrapped in the expected <turbo-frame id="agreement_modal_frame">...</turbo-frame>
+    # so Turbo can swap it into the frame. For normal requests, fall back to the
+    # default rendering (with layout).
+    def show
+      if @agreement.page
+        @page = @agreement.page
+        @content_blocks = @page.content_blocks
+        @layout = 'layouts/better_together/page'
+        @layout = @page.layout if @page.layout.present?
+      end
+
+      return unless turbo_frame_request?
+
+      content = render_to_string(action: :show, layout: false)
+      render html: "<turbo-frame id=\"agreement_modal_frame\">#{content}</turbo-frame>".html_safe
+    end
+
+    protected
+
+    def resource_class
+      ::BetterTogether::Agreement
+    end
+  end
+end

app/controllers/better_together/users/registrations_controller.rb

@@ -7,6 +7,7 @@ class RegistrationsController < ::Devise::RegistrationsController
       include DeviseLocales
 
       skip_before_action :check_platform_privacy
+      before_action :set_required_agreements, only: %i[new create]
 
       def new
         super do |user|
@@ -15,9 +16,15 @@ def new
       end
 
       def create # rubocop:todo Metrics/MethodLength, Metrics/AbcSize
-        ActiveRecord::Base.transaction do
+        unless agreements_accepted?
+          build_resource(sign_up_params)
+          resource.errors.add(:base, I18n.t('devise.registrations.new.agreements_required'))
+          respond_with resource
+          return
+        end
+
+        ActiveRecord::Base.transaction do # rubocop:todo Metrics/BlockLength
           super do |user|
-            # byebug
             return unless user.persisted?
 
             user.build_person(person_params)
@@ -46,13 +53,21 @@ def create # rubocop:todo Metrics/MethodLength, Metrics/AbcSize
 
                 @platform_invitation.accept!(invitee: user.person)
               end
+
+              create_agreement_participants(user.person)
             end
           end
         end
       end
 
       protected
 
+      def set_required_agreements
+        @privacy_policy_agreement = BetterTogether::Agreement.find_by(identifier: 'privacy_policy')
+        @terms_of_service_agreement = BetterTogether::Agreement.find_by(identifier: 'terms_of_service')
+        @code_of_conduct_agreement = BetterTogether::Agreement.find_by(identifier: 'code_of_conduct')
+      end
+
       def after_sign_up_path_for(resource)
         if is_navigational_format? && helpers.host_platform&.privacy_private?
           return better_together.new_user_session_path
@@ -72,6 +87,23 @@ def after_inactive_sign_up_path_for(resource)
       def person_params
         params.require(:user).require(:person_attributes).permit(%i[identifier name description])
       end
+
+      def agreements_accepted?
+        required = [params[:privacy_policy_agreement], params[:terms_of_service_agreement]]
+        # If a code of conduct agreement exists, require it as well
+        required << params[:code_of_conduct_agreement] if @code_of_conduct_agreement.present?
+
+        required.all? { |v| v == '1' }
+      end
+
+      def create_agreement_participants(person)
+        identifiers = %w[privacy_policy terms_of_service]
+        identifiers << 'code_of_conduct' if BetterTogether::Agreement.exists?(identifier: 'code_of_conduct')
+        agreements = BetterTogether::Agreement.where(identifier: identifiers)
+        agreements.find_each do |agreement|
+          BetterTogether::AgreementParticipant.create!(agreement: agreement, person: person, accepted_at: Time.current)
+        end
+      end
     end
   end
 end

app/helpers/better_together/agreements_helper.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module BetterTogether
+  # Helpers for Agreements
+  module AgreementsHelper
+  end
+end