Implement Block Management Interface with Search and Unblock Features

- Added `rails-controller-testing` gem for enhanced controller testing.
- Updated `PersonBlocksController` to include search functionality for blocked users and display blocking timestamps.
- Created views for managing blocked users, including index and new block forms.
- Implemented AJAX responses for blocking and unblocking users with Turbo Streams.
- Enhanced policies to manage user permissions for blocking actions.
- Added acceptance criteria documentation for the Block Management Interface.
- Developed comprehensive controller specs to ensure functionality and edge cases are covered.

Author: rsmithlal

.github/copilot-instructions.md

@@ -12,32 +12,36 @@ Instructions for GitHub Copilot and other automated contributors working in this
 
 ## Setup
 - Environment runs a setup script that installs Ruby 3.4.4, Node 20, Postgres + PostGIS, and ES7, then prepares databases.
+- **Docker Environment**: All commands requiring database access must use `bin/dc-run` to execute within the containerized environment.
+- **Dummy App Commands**: Use `bin/dc-run-dummy` for Rails commands that need the dummy app context (e.g., `bin/dc-run-dummy rails console`, `bin/dc-run-dummy rails db:migrate`).
 - Databases:
   - development: `community_engine_development`
   - test: `community_engine_test`
 - Use `DATABASE_URL` to connect (overrides fallback host in `config/database.yml`).
 
 ## Commands
-- **Tests:** `bin/ci`
-  (Equivalent: `cd spec/dummy && bundle exec rspec`)
+- **Tests:** `bin/dc-run bin/ci`
+  (Equivalent: `bin/dc-run bash -c "cd spec/dummy && bundle exec rspec"`)
 - **Running specific tests:** 
-  - Single spec file: `bundle exec rspec spec/path/to/file_spec.rb`
-  - Specific line: `bundle exec rspec spec/path/to/file_spec.rb:123`
-  - Multiple files: `bundle exec rspec spec/file1_spec.rb spec/file2_spec.rb`
-  - Multiple specific lines: `bundle exec rspec spec/file1_spec.rb:123 spec/file2_spec.rb:456`
+  - Single spec file: `bin/dc-run bundle exec rspec spec/path/to/file_spec.rb`
+  - Specific line: `bin/dc-run bundle exec rspec spec/path/to/file_spec.rb:123`
+  - Multiple files: `bin/dc-run bundle exec rspec spec/file1_spec.rb spec/file2_spec.rb`
+  - Multiple specific lines: `bin/dc-run bundle exec rspec spec/file1_spec.rb:123 spec/file2_spec.rb:456`
   - **Important**: RSpec does NOT support hyphenated line numbers (e.g., `spec/file_spec.rb:123-456` is INVALID)
-- **Lint:** `bundle exec rubocop`
-- **Security:** `bundle exec brakeman --quiet --no-pager` and `bundle exec bundler-audit --update`
-- **Style:** `bin/codex_style_guard`
-- **I18n:** `bin/i18n [normalize|check|health|all]` (runs normalize + missing + interpolation checks by default)
+- **Rails Console:** `bin/dc-run-dummy rails console` (runs console in the dummy app context)
+- **Rails Commands in Dummy App:** `bin/dc-run-dummy rails [command]` for any Rails commands that need the dummy app environment
+- **Lint:** `bin/dc-run bundle exec rubocop`
+- **Security:** `bin/dc-run bundle exec brakeman --quiet --no-pager` and `bin/dc-run bundle exec bundler-audit --update`
+- **Style:** `bin/dc-run bin/codex_style_guard`
+- **I18n:** `bin/dc-run bin/i18n [normalize|check|health|all]` (runs normalize + missing + interpolation checks by default)
 - **Documentation:**
   - **Table of Contents**: [`docs/table_of_contents.md`](docs/table_of_contents.md) - Main documentation index
   - **Progress tracking**: `docs/scripts/update_progress.sh` - Update system completion status
   - **Diagram rendering**: `bin/render_diagrams` - Generate PNG/SVG from Mermaid sources
   - **Validation**: `docs/scripts/validate_documentation_tooling.sh` - Validate doc system integrity
 
 ## Security Requirements
-- **Run Brakeman before generating code**: `bundle exec brakeman --quiet --no-pager` 
+- **Run Brakeman before generating code**: `bin/dc-run 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:**
@@ -47,11 +51,11 @@ Instructions for GitHub Copilot and other automated contributors working in this
   - Use strong parameters in controllers
   - Implement proper authorization checks (Pundit policies)
 - **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
+- **Post-generation security check**: Run `bin/dc-run bundle exec brakeman --quiet --no-pager -c UnsafeReflection,SQL,CrossSiteScripting` after major code changes
 
 ## Conventions
 - Make incremental changes with passing tests.
-- **Security first**: Run `bundle exec brakeman --quiet --no-pager` before committing code changes.
+- **Security first**: Run `bin/dc-run bundle exec brakeman --quiet --no-pager` before committing code changes.
 - **Test every change**: Generate RSpec tests for all code modifications, including models, controllers, mailers, jobs, and JavaScript.
 - **Test coverage requirements**: All new features, bug fixes, and refactors must include comprehensive test coverage.
 - Avoid introducing new external services in tests; stub where possible.
@@ -156,14 +160,14 @@ We use the `i18n-tasks` gem to ensure all translation keys are present, normaliz
 
 ## Example Commands
 ```bash
-i18n-tasks normalize
-i18n-tasks missing
-i18n-tasks add-missing
-i18n-tasks health
+bin/dc-run i18n-tasks normalize
+bin/dc-run i18n-tasks missing
+bin/dc-run i18n-tasks add-missing
+bin/dc-run i18n-tasks health
 ```
 
 ## CI Note
-- The i18n GitHub Action installs dev/test gem groups to make `i18n-tasks` available. Locally, you can mirror CI with `bin/i18n`, which sets `BUNDLE_WITH=development:test` automatically.
+- The i18n GitHub Action installs dev/test gem groups to make `i18n-tasks` available. Locally, you can mirror CI with `bin/dc-run bin/i18n`, which sets `BUNDLE_WITH=development:test` automatically.
 
 See `.github/instructions/i18n-mobility.instructions.md` for additional translation rules.
 
@@ -205,6 +209,22 @@ For every implementation plan, create acceptance criteria covering relevant stak
 - **Test all layers**: models (validations, associations, methods), controllers (actions, authorization), services, mailers, jobs, and view components.
 - **JavaScript/Stimulus testing**: Include feature specs that exercise dynamic behaviors like form interactions and AJAX updates.
 
+## Test Environment Requirements
+- **Host Platform Configuration**: All controller, request, and feature tests MUST configure the host platform/community before testing.
+- **Use `configure_host_platform`**: Call this helper method in a `before` block for any test that makes HTTP requests or tests authentication/authorization.
+- **DeviseSessionHelpers**: Include this module and use authentication helpers like `login('[email protected]', 'password')` for authenticated tests.
+- **Platform Setup Pattern**:
+  ```ruby
+  RSpec.describe BetterTogether::SomeController do
+    before do
+      configure_host_platform  # Creates host platform with community
+      login('[email protected]', 'password')  # For authenticated tests
+    end
+  end
+  ```
+- **Required for**: Controller specs, request specs, feature specs, and any integration tests that involve routing or authentication.
+- **Locale Parameters**: Engine controller tests require locale parameters (e.g., `params: { locale: I18n.default_locale }`) due to routing constraints.
+
 ## Test Coverage Standards
 - **Models**: Test validations, associations, scopes, instance methods, class methods, and callbacks.
 - **Controllers**: Test all actions, authorization policies, parameter handling, and response formats.
@@ -315,3 +335,70 @@ Each major system must include:
 - Security implications and access controls
 - API endpoints with request/response examples
 - Monitoring tools and troubleshooting procedures
+
+## Testing Architecture Consistency Lessons Learned
+
+### Critical Testing Pattern: Request Specs vs Controller Specs
+- **Project Standard**: All tests use request specs (`type: :request`) for consistency with Rails engine routing
+- **Exception Handling**: Controller specs (`type: :controller`) require special URL helper configuration in Rails engines
+- **Why This Matters**: Request specs handle Rails engine routing automatically through the full HTTP stack, while controller specs test in isolation and need explicit configuration
+- **Debugging Indicator**: If you see `default_url_options` errors only in one spec while others pass, check if it's a controller spec in a request spec codebase
+
+### Rails Engine URL Helper Configuration
+- **Problem**: Controller specs in Rails engines throw `default_url_options` errors that request specs don't encounter
+- **Root Cause**: Engines need special URL helper setup for controller specs but not request specs
+- **Solution Patterns**:
+  ```ruby
+  # For controller spec assertions, use pattern matching instead of path helpers:
+  expect(response.location).to include('/person_blocks') # Good
+  expect(response).to redirect_to(person_blocks_path) # Problematic in controller specs
+  
+  # Ensure consistent route naming throughout:
+  # Controller: person_blocks_path (not blocks_path)
+  # Views: <%= link_to "Block", better_together.person_blocks_path %>
+  # Tests: params path should match controller actions
+  ```
+
+### Route Naming Convention Enforcement
+- **Pattern**: Engine routes follow full resource naming: `better_together.resource_name_path`
+- **Common Error**: Using shortened path names (`blocks_path`) instead of full names (`person_blocks_path`)
+- **Consistency Check**: Views, controllers, and tests must all use the same complete path helper names
+- **Verification**: Check all three layers when debugging routing issues
+
+### Factory and Association Dependencies
+- **Requirement**: Every Better Together model needs a corresponding FactoryBot factory
+- **Naming Convention**: Factory names follow `better_together_model_name` pattern with aliases
+- **Association Setup**: Factories must properly handle engine namespace associations
+- **Missing Factory Indicator**: Tests failing on association creation often indicate missing factories
+
+### Test Environment Configuration Enforcement
+- **Critical Setup**: `configure_host_platform` must be called before any controller/request/feature tests
+- **Why Required**: Better Together engine needs host platform setup for authentication and authorization
+- **Pattern Recognition**: Tests failing with authentication/authorization errors often need this setup
+- **Documentation Reference**: This pattern is well-documented but bears reinforcement
+
+### Architecture Consistency Principles
+- **Consistency Is Key**: When one component (PersonBlocksController) differs from project patterns, it requires special handling
+- **Pattern Detection**: Single anomalies (one controller spec among many request specs) signal architectural inconsistencies
+- **Prevention**: New tests should follow the established pattern (request specs) unless there's a compelling reason for exceptions
+- **Documentation**: When exceptions are necessary, document why they exist and how to handle their special requirements
+
+### Testing Strategy Recommendations
+- **Default Choice**: Use request specs for new controller tests to maintain consistency
+- **Engine Compatibility**: Request specs handle Rails engine complexity automatically
+- **Special Cases**: If controller specs are needed, prepare for URL helper configuration complexity
+- **Debugging Approach**: When testing errors occur in only one spec, compare its type and setup to working specs
+
+## Docker Environment Usage
+- **All database-dependent commands must use `bin/dc-run`**: This includes tests, generators, and any command that connects to PostgreSQL, Redis, or Elasticsearch
+- **Dummy app commands use `bin/dc-run-dummy`**: For Rails commands that need the dummy app context (console, migrations specific to dummy app)
+- **Examples of commands requiring `bin/dc-run`**:
+  - Tests: `bin/dc-run bundle exec rspec`
+  - Generators: `bin/dc-run rails generate model User`
+  - Brakeman: `bin/dc-run bundle exec brakeman`
+  - RuboCop: `bin/dc-run bundle exec rubocop`
+- **Examples of commands requiring `bin/dc-run-dummy`**:
+  - Rails console: `bin/dc-run-dummy rails console`
+  - Dummy app migrations: `bin/dc-run-dummy rails db:migrate`
+  - Dummy app database operations: `bin/dc-run-dummy rails db:seed`
+- **Commands that don't require bin/dc-run**: File operations, documentation generation (unless database access needed), static analysis tools that don't connect to services

AGENTS.md

@@ -105,6 +105,8 @@ group :test do
   gem 'database_cleaner-active_record'
   # # Easy installation and use of chromedriver to run system tests with Chrome
   # gem 'webdrivers'
+  # Rails controller testing for assigns method
+  gem 'rails-controller-testing'
   # RuboCop RSpec for RSpec-specific code analysis
   gem 'rubocop-capybara'
   gem 'rubocop-factory_bot'

Gemfile

@@ -562,6 +562,10 @@ GEM
       activesupport (= 7.1.5.2)
       bundler (>= 1.15.0)
       railties (= 7.1.5.2)
+    rails-controller-testing (1.0.5)
+      actionpack (>= 5.0.1.rc1)
+      actionview (>= 5.0.1.rc1)
+      activesupport (>= 5.0.1.rc1)
     rails-dom-testing (2.3.0)
       activesupport (>= 5.0.0)
       minitest
@@ -846,6 +850,7 @@ DEPENDENCIES
   rack-mini-profiler
   rack-protection
   rails (= 7.1.5.2)
+  rails-controller-testing
   rb-readline
   rbtrace
   redis (~> 5.4)

Gemfile.lock

@@ -2,39 +2,116 @@
 
 module BetterTogether
   class PersonBlocksController < ApplicationController # rubocop:todo Style/Documentation
+    before_action :authenticate_user!
     before_action :set_person_block, only: :destroy
     after_action :verify_authorized
 
-    def index
+    def index # rubocop:todo Metrics/AbcSize, Metrics/MethodLength
       authorize PersonBlock
-      @blocked_people = current_person.blocked_people
+
+      # AC-2.11: I can search through my blocked users by name
+      @blocked_people = helpers.current_person.blocked_people
+      if params[:search].present?
+        # Search by translated name using includes and references
+        # Apply policy scope to ensure only authorized people are searchable
+        search_term = params[:search].strip
+        authorized_person_ids = policy_scope(BetterTogether::Person).pluck(:id)
+
+        @blocked_people = @blocked_people.where(id: authorized_person_ids)
+                                         .includes(:string_translations)
+                                         .references(:string_translations)
+                                         .where(string_translations: { key: 'name' })
+                                         .where('string_translations.value ILIKE ?', "%#{search_term}%")
+                                         .distinct
+      end
+
+      # AC-2.12: I can see when I blocked each user (provide person_blocks for timestamp info)
+      @person_blocks = helpers.current_person.person_blocks.includes(:blocked)
+      if params[:search].present?
+        # Filter person_blocks by matching blocked person names
+        # Apply policy scope to ensure only authorized people are searchable
+        search_term = params[:search].strip
+        authorized_person_ids = policy_scope(BetterTogether::Person).pluck(:id)
+
+        @person_blocks = @person_blocks.joins(:blocked)
+                                       .where(better_together_people: { id: authorized_person_ids })
+                                       .includes(blocked: :string_translations)
+                                       .references(:string_translations)
+                                       .where(string_translations: { key: 'name' })
+                                       .where('string_translations.value ILIKE ?', "%#{search_term}%")
+                                       .distinct
+      end
+
+      # AC-2.15: I can see how many users I have blocked
+      @blocked_count = @blocked_people.count
     end
 
-    def create
-      @person_block = current_person.person_blocks.new(person_block_params)
-      authorize @person_block
+    def new
+      authorize PersonBlock
+      @person_block = helpers.current_person.person_blocks.build
+    end
 
-      if @person_block.save
-        redirect_to blocks_path, notice: t('flash.person_block.blocked')
-      else
-        redirect_to blocks_path, alert: @person_block.errors.full_messages.to_sentence
+    def create # rubocop:todo Metrics/AbcSize, Metrics/MethodLength
+        # rubocop:todo Layout/IndentationWidth
+        @person_block = helpers.current_person.person_blocks.new(person_block_params)
+  # rubocop:enable Layout/IndentationWidth
+
+  # AC-2.13: I can block a user by entering their username or email
+  if params[:person_block][:blocked_identifier].present? # rubocop:todo Layout/IndentationConsistency
+    target_person = BetterTogether::Person.find_by(identifier: params[:person_block][:blocked_identifier]) ||
+                    # rubocop:todo Layout/LineLength
+                    BetterTogether::Person.joins(:user).find_by(better_together_users: { email: params[:person_block][:blocked_identifier] })
+    # rubocop:enable Layout/LineLength
+    @person_block.blocked = target_person if target_person
+  end
+
+  authorize @person_block # rubocop:todo Layout/IndentationConsistency
+
+  respond_to do |format| # rubocop:todo Layout/IndentationConsistency
+    if @person_block.save
+      # AC-2.9: I receive confirmation when blocking/unblocking users
+      flash[:notice] = t('better_together.person_blocks.notices.blocked')
+      format.html { redirect_to person_blocks_path }
+      format.turbo_stream do
+        render turbo_stream: turbo_stream.replace('blocked_people_list', partial: 'index_content')
+      end
+    else
+      flash[:alert] = @person_block.errors.full_messages.to_sentence
+      format.html { redirect_to person_blocks_path }
+      format.turbo_stream do
+        render turbo_stream: turbo_stream.replace('flash_messages', partial: 'shared/flash_messages')
       end
     end
+  end
+    end
 
     def destroy
       authorize @person_block
       @person_block.destroy
-      redirect_to blocks_path, notice: t('flash.person_block.unblocked')
+
+      respond_to do |format|
+        # AC-2.9: I receive confirmation when blocking/unblocking users
+        flash[:notice] = t('better_together.person_blocks.notices.unblocked')
+        format.html { redirect_to person_blocks_path }
+        format.turbo_stream do
+          render turbo_stream: turbo_stream.replace('blocked_people_list', partial: 'index_content')
+        end
+      end
     end
 
     private
 
-    def current_person
-      current_user.person
+    def locale
+      params[:locale] || I18n.default_locale
     end
 
     def set_person_block
+      current_person = helpers.current_person
+      return render_not_found unless current_person
+
       @person_block = current_person.person_blocks.find(params[:id])
+    rescue ActiveRecord::RecordNotFound
+      render_not_found
     end
 
     def person_block_params

app/controllers/better_together/person_blocks_controller.rb

@@ -6,6 +6,10 @@ def index?
       user.present?
     end
 
+    def new?
+      user.present?
+    end
+
     def create?
       user.present? && record.blocker == agent && !record.blocked.permitted_to?('manage_platform')
     end