Add service dependency checking to bin/dev (#2098)

## Summary

This PR introduces a service dependency checking system that validates
required external services (like Redis, PostgreSQL, Elasticsearch) are
running before `bin/dev` starts the development server.

## Problem

Many applications depend on external services that must be running
before the dev server starts. Currently, there are two approaches:

1. **Include services in Procfile** (e.g., `redis: redis-server`) -
Works but clutters the Procfile
2. **Let Procfile fail** - Results in cryptic errors that confuse new
developers

Neither approach is ideal. The Procfile is meant for application
processes, not infrastructure services.

## Solution

A new `.dev-services.yml` configuration file that:
- Declaratively defines required services
- Checks if they're running before starting Procfile
- Provides helpful error messages with start commands
- Works cross-platform (macOS and Linux)
- Has zero impact if not used

## Key Features

✅ **Declarative configuration** - Simple YAML format
✅ **Self-documenting** - Includes `.dev-services.yml.example` template
✅ **Helpful errors** - Clear instructions on how to start missing
services
✅ **Cross-platform** - Works on macOS and Linux
✅ **Zero impact** - If no config exists, bin/dev works exactly as before
✅ **Test coverage** - 11 comprehensive tests, all passing

## Configuration Example

```yaml
services:
  redis:
    check_command: "redis-cli ping"
    expected_output: "PONG"
    start_command: "redis-server"
    install_hint: "brew install redis (macOS) or apt-get install redis-server (Linux)"
    description: "Redis (for caching and background jobs)"

  postgresql:
    check_command: "pg_isready"
    expected_output: "accepting connections"
    start_command: "pg_ctl -D /usr/local/var/postgres start"
    description: "PostgreSQL database"
```

## User Experience

**When all services are running:**
```
🔍 Checking required services (.dev-services.yml)...

   ✓ redis - Redis (for caching and background jobs)
   ✓ postgresql - PostgreSQL database

✅ All services are running

[Procfile starts normally]
```

**When services are missing:**
```
🔍 Checking required services (.dev-services.yml)...

   ✗ redis - Redis (for caching and background jobs)

❌ Some services are not running

Please start these services before running bin/dev:

redis
   Redis (for caching and background jobs)

   To start:
   redis-server

   Not installed? brew install redis (macOS) or apt-get install redis-server (Linux)

💡 Tips:
   • Start services manually, then run bin/dev again
   • Or remove service from .dev-services.yml if not needed
   • Or add service to Procfile.dev to start automatically
```

## Implementation Details

### New Files
- `lib/react_on_rails/dev/service_checker.rb` - Core service checking
logic
- `spec/react_on_rails/dev/service_checker_spec.rb` - Comprehensive test
suite
-
`lib/generators/react_on_rails/templates/base/base/.dev-services.yml.example`
- Template for new projects
- `spec/dummy/.dev-services.yml.example` - Example for dummy app

### Modified Files
- `lib/react_on_rails/dev/server_manager.rb` - Integrated service checks
before starting Procfile
- `lib/generators/react_on_rails/base_generator.rb` - Added
`.dev-services.yml.example` to generated files

### Service Checking Flow
1. Check if `.dev-services.yml` exists (if not, continue normally)
2. Load and parse YAML configuration
3. Run each service's `check_command`
4. Validate output against `expected_output` (if specified)
5. If all pass: continue to start Procfile
6. If any fail: display helpful errors and exit

## Benefits

🎯 **Self-documenting** - New developers see exactly what services are
needed
🎯 **Cleaner Procfiles** - Remove infrastructure services, keep only app
processes
🎯 **Better onboarding** - Clear instructions instead of cryptic failures
🎯 **Flexible** - Each app can define its own requirements
🎯 **Optional** - Zero impact on existing installations

## Test Plan

- [x] All 11 new tests passing
- [x] All existing dev module tests still passing (89 total)
- [x] RuboCop clean
- [x] Pre-commit hooks passing
- [x] Manual testing with dummy app

## Breaking Changes

None. This is purely additive. If `.dev-services.yml` doesn't exist,
`bin/dev` behaves exactly as before.

## Future Enhancements

Potential future improvements:
- Auto-start services with user confirmation
- Integration with Docker Compose
- Service health monitoring during development
- Template snippets for common services

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* Added Service Dependency Checking for `bin/dev`: An optional
`.dev-services.yml` configuration file validates external services
(Redis, PostgreSQL, Elasticsearch, etc.) are running before the
development server starts. Provides clear error messages with startup
and installation guidance when services are missing. Fully backward
compatible—disabled by default.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: justin808

CHANGELOG.md

@@ -23,6 +23,10 @@ After a release, please make sure to run `bundle exec rake update_changelog`. Th
 
 Changes since the last non-beta release.
 
+#### Added
+
+- **Service Dependency Checking for bin/dev**: Added optional `.dev-services.yml` configuration to validate required external services (Redis, PostgreSQL, Elasticsearch, etc.) are running before `bin/dev` starts the development server. Provides clear error messages with start commands and install hints when services are missing. Zero impact if not configured - backwards compatible with all existing installations. [PR 2098](https://github.com/shakacode/react_on_rails/pull/2098) by [justin808](https://github.com/justin808).
+
 #### Improved
 
 - **Automatic Precompile Hook Coordination in bin/dev**: The `bin/dev` command now automatically runs Shakapacker's `precompile_hook` once before starting development processes and sets `SHAKAPACKER_SKIP_PRECOMPILE_HOOK=true` to prevent duplicate execution in spawned webpack processes.

Steepfile

@@ -32,6 +32,7 @@ target :lib do
   check "lib/react_on_rails/dev/pack_generator.rb"
   check "lib/react_on_rails/dev/process_manager.rb"
   check "lib/react_on_rails/dev/server_manager.rb"
+  check "lib/react_on_rails/dev/service_checker.rb"
   check "lib/react_on_rails/git_utils.rb"
   check "lib/react_on_rails/helper.rb"
   check "lib/react_on_rails/packer_utils.rb"

docs/building-features/process-managers.md

@@ -16,11 +16,12 @@ React on Rails includes `bin/dev` which automatically uses Overmind or Foreman:
 
 This script will:
 
-1. Run Shakapacker's `precompile_hook` once (if configured in `config/shakapacker.yml`)
-2. Set `SHAKAPACKER_SKIP_PRECOMPILE_HOOK=true` to prevent duplicate execution
-3. Try to use Overmind (if installed)
-4. Fall back to Foreman (if installed)
-5. Show installation instructions if neither is found
+1. Check required external services (if `.dev-services.yml` exists)
+2. Run Shakapacker's `precompile_hook` once (if configured in `config/shakapacker.yml`)
+3. Set `SHAKAPACKER_SKIP_PRECOMPILE_HOOK=true` to prevent duplicate execution
+4. Try to use Overmind (if installed)
+5. Fall back to Foreman (if installed)
+6. Show installation instructions if neither is found
 
 ### Precompile Hook Integration
 
@@ -57,6 +58,111 @@ default: &default
 
 See the [i18n documentation](./i18n.md#internationalization) for more details on configuring the precompile hook.
 
+### Service Dependency Checking
+
+`bin/dev` can automatically verify that required external services (like Redis, PostgreSQL, Elasticsearch) are running before starting your development server. This prevents cryptic error messages and provides clear instructions on how to start missing services.
+
+#### Configuration
+
+Create a `.dev-services.yml` file in your project root:
+
+```yaml
+services:
+  redis:
+    check_command: 'redis-cli ping'
+    expected_output: 'PONG'
+    start_command: 'redis-server'
+    install_hint: 'brew install redis (macOS) or apt-get install redis-server (Linux)'
+    description: 'Redis (for caching and background jobs)'
+
+  postgresql:
+    check_command: 'pg_isready'
+    expected_output: 'accepting connections'
+    start_command: 'pg_ctl -D /usr/local/var/postgres start'
+    install_hint: 'brew install postgresql (macOS)'
+    description: 'PostgreSQL database'
+```
+
+A `.dev-services.yml.example` file with common service configurations is created when you run the React on Rails generator.
+
+#### Configuration Fields
+
+- **check_command** (required): Shell command to check if the service is running
+- **expected_output** (optional): String that must appear in the command output
+- **start_command** (optional): Command to start the service (shown in error messages)
+- **install_hint** (optional): How to install the service if not found
+- **description** (optional): Human-readable description of the service
+
+#### Behavior
+
+If `.dev-services.yml` exists, `bin/dev` will:
+
+1. Check each configured service before starting
+2. Show a success message if all services are running
+3. Show helpful error messages with start commands if any service is missing
+4. Exit before starting the Procfile if services are unavailable
+
+If `.dev-services.yml` doesn't exist, `bin/dev` works exactly as before (zero impact on existing installations).
+
+#### Example Output
+
+**When services are running:**
+
+```
+🔍 Checking required services (.dev-services.yml)...
+
+   ✓ redis - Redis (for caching and background jobs)
+   ✓ postgresql - PostgreSQL database
+
+✅ All services are running
+```
+
+**When services are missing:**
+
+```
+🔍 Checking required services (.dev-services.yml)...
+
+   ✗ redis - Redis (for caching and background jobs)
+
+❌ Some services are not running
+
+Please start these services before running bin/dev:
+
+redis
+   Redis (for caching and background jobs)
+
+   To start:
+   redis-server
+
+   Not installed? brew install redis (macOS) or apt-get install redis-server (Linux)
+
+💡 Tips:
+   • Start services manually, then run bin/dev again
+   • Or remove service from .dev-services.yml if not needed
+   • Or add service to Procfile.dev to start automatically
+```
+
+#### Security Note
+
+⚠️ **IMPORTANT**: Commands in `.dev-services.yml` are executed during `bin/dev` startup without shell expansion for safety. However, you should still:
+
+- **Only add commands from trusted sources**
+- **Avoid shell metacharacters** (&&, ||, ;, |, $, etc.) - they won't work and indicate an anti-pattern
+- **Review changes carefully** if .dev-services.yml is committed to version control
+- **Consider adding to .gitignore** if it contains machine-specific paths or sensitive information
+
+**Recommended approach:**
+
+- Commit `.dev-services.yml.example` to version control (safe, documentation)
+- Add `.dev-services.yml` to `.gitignore` (developers copy from example)
+- This prevents accidental execution of untrusted commands from compromised dependencies
+
+**Execution order:**
+
+1. Service dependency checks (`.dev-services.yml`)
+2. Precompile hook (if configured in `config/shakapacker.yml`)
+3. Process manager starts processes from Procfile
+
 ## Installing a Process Manager
 
 ### Overmind (Recommended)

lib/generators/react_on_rails/base_generator.rb

@@ -46,6 +46,7 @@ def copy_base_files
                         Procfile.dev
                         Procfile.dev-static-assets
                         Procfile.dev-prod-assets
+                        .dev-services.yml.example
                         bin/shakapacker-precompile-hook]
         base_templates = %w[config/initializers/react_on_rails.rb]
         base_files.each { |file| copy_file("#{base_path}#{file}", file) }

lib/generators/react_on_rails/templates/base/base/.dev-services.yml.example

@@ -0,0 +1,76 @@
+# Service Dependencies Configuration
+#
+# This file defines external services that must be running before bin/dev starts.
+# Copy this file to .dev-services.yml and customize for your application.
+#
+# bin/dev will check each service before starting the development server.
+# If any service is not running, it will display helpful error messages with
+# instructions on how to start the service.
+#
+# ⚠️  SECURITY WARNING:
+# Commands in this file are executed during bin/dev startup. Only add commands
+# from trusted sources. This file should not be committed if it contains
+# sensitive information or custom paths specific to your machine. Consider
+# adding .dev-services.yml to .gitignore if it contains machine-specific config.
+#
+# Security best practices:
+# - Commands are executed without shell expansion (shell metacharacters won't work)
+# - Use simple, single commands (e.g., "redis-cli ping", "pg_isready")
+# - Do NOT use shell features: &&, ||, |, $, ;, backticks, etc. will fail
+# - Only include services you trust
+# - Keep commands simple and focused on service health checks
+# - Consider adding .dev-services.yml to .gitignore (commit .example instead)
+#
+# Example configuration:
+#
+# services:
+#   redis:
+#     check_command: "redis-cli ping"
+#     expected_output: "PONG"
+#     start_command: "redis-server"
+#     install_hint: "brew install redis (macOS) or apt-get install redis-server (Linux)"
+#     description: "Redis (for caching and background jobs)"
+#
+#   postgresql:
+#     check_command: "pg_isready"
+#     expected_output: "accepting connections"
+#     start_command: "pg_ctl -D /usr/local/var/postgres start"
+#     install_hint: "brew install postgresql (macOS) or apt-get install postgresql (Linux)"
+#     description: "PostgreSQL database"
+#
+#   elasticsearch:
+#     check_command: "curl -s http://localhost:9200"
+#     expected_output: "cluster_name"
+#     start_command: "brew services start elasticsearch-full"
+#     install_hint: "brew install elasticsearch-full"
+#     description: "Elasticsearch (for search)"
+#
+# Field descriptions:
+#   check_command:    Shell command to check if service is running (required)
+#   expected_output:  String that must appear in command output (optional)
+#   start_command:    Command to start the service (shown in error messages)
+#   install_hint:     How to install the service if not found
+#   description:      Human-readable description of the service
+#
+# To use this file:
+# 1. Copy to .dev-services.yml: cp .dev-services.yml.example .dev-services.yml
+# 2. Uncomment and configure the services your app needs
+# 3. Add .dev-services.yml to .gitignore if it contains sensitive info
+# 4. Run bin/dev - it will check services before starting
+
+services:
+  # Uncomment and configure the services your application requires:
+
+  # redis:
+  #   check_command: "redis-cli ping"
+  #   expected_output: "PONG"
+  #   start_command: "redis-server"
+  #   install_hint: "brew install redis (macOS) or apt-get install redis-server (Linux)"
+  #   description: "Redis (for caching and background jobs)"
+
+  # postgresql:
+  #   check_command: "pg_isready"
+  #   expected_output: "accepting connections"
+  #   start_command: "pg_ctl -D /usr/local/var/postgres start"  # macOS; Linux: sudo service postgresql start
+  #   install_hint: "brew install postgresql (macOS) or apt-get install postgresql (Linux)"
+  #   description: "PostgreSQL database"

lib/react_on_rails/dev/server_manager.rb

@@ -4,6 +4,7 @@
 require "open3"
 require "rainbow"
 require_relative "../packer_utils"
+require_relative "service_checker"
 
 module ReactOnRails
   module Dev
@@ -330,6 +331,7 @@ def help_options
         end
         # rubocop:enable Metrics/AbcSize
 
+        # rubocop:disable Metrics/AbcSize
         def help_customization
           <<~CUSTOMIZATION
             #{Rainbow('🔧 CUSTOMIZATION:').cyan.bold}
@@ -340,8 +342,24 @@ def help_customization
             #{Rainbow('•').yellow} #{Rainbow('Procfile.dev-prod-assets').green.bold}     - Production-optimized assets (port 3001)
 
             #{Rainbow('Edit these files to customize the development environment for your needs.').white}
+
+            #{Rainbow('🔍 SERVICE DEPENDENCIES:').cyan.bold}
+            #{Rainbow('Configure required external services in').white} #{Rainbow('.dev-services.yml').green.bold}#{Rainbow(':').white}
+
+            #{Rainbow('•').yellow} #{Rainbow('bin/dev').white} #{Rainbow('checks services before starting (optional)').white}
+            #{Rainbow('•').yellow} #{Rainbow('Copy from').white} #{Rainbow('.dev-services.yml.example').green.bold} #{Rainbow('to get started').white}
+            #{Rainbow('•').yellow} #{Rainbow('Supports Redis, PostgreSQL, Elasticsearch, and custom services').white}
+            #{Rainbow('•').yellow} #{Rainbow('Shows helpful errors with start commands if services are missing').white}
+
+            #{Rainbow('Example .dev-services.yml:').white}
+            #{Rainbow('  services:').cyan}
+            #{Rainbow('    redis:').cyan}
+            #{Rainbow('      check_command: "redis-cli ping"').cyan}
+            #{Rainbow('      expected_output: "PONG"').cyan}
+            #{Rainbow('      start_command: "redis-server"').cyan}
           CUSTOMIZATION
         end
+        # rubocop:enable Metrics/AbcSize
 
         # rubocop:disable Metrics/AbcSize
         def help_mode_details
@@ -392,6 +410,10 @@ def run_production_like(_verbose: false, route: nil, rails_env: nil)
           # either via precompile hook or via the configuration.rb adjust_precompile_task
 
           print_procfile_info(procfile, route: route)
+
+          # Check required services before starting
+          exit 1 unless ServiceChecker.check_services
+
           print_server_info(
             "🏭 Starting production-like development server...",
             features,
@@ -514,6 +536,9 @@ def run_production_like(_verbose: false, route: nil, rails_env: nil)
         def run_static_development(procfile, verbose: false, route: nil)
           print_procfile_info(procfile, route: route)
 
+          # Check required services before starting
+          exit 1 unless ServiceChecker.check_services
+
           features = [
             "Using shakapacker --watch (no HMR)",
             "CSS extracted to separate files (no FOUC)",
@@ -539,6 +564,10 @@ def run_static_development(procfile, verbose: false, route: nil)
 
         def run_development(procfile, verbose: false, route: nil)
           print_procfile_info(procfile, route: route)
+
+          # Check required services before starting
+          exit 1 unless ServiceChecker.check_services
+
           PackGenerator.generate(verbose: verbose)
           ProcessManager.ensure_procfile(procfile)
           ProcessManager.run_with_process_manager(procfile)