react_on_rails 16.1.2 → 16.2.0

data/lib/react_on_rails/dev/server_manager.rb

@@ -3,10 +3,14 @@
 require "English"
 require "open3"
 require "rainbow"
+require_relative "../packer_utils"
+require_relative "service_checker"
 
 module ReactOnRails
   module Dev
     class ServerManager
+      HELP_FLAGS = ["-h", "--help"].freeze
+
       class << self
         def start(mode = :development, procfile = nil, verbose: false, route: nil, rails_env: nil)
           case mode
@@ -27,7 +31,7 @@ module ReactOnRails
           puts "🔪 Killing all development processes..."
           puts ""
 
-          killed_any = kill_running_processes || cleanup_socket_files
+          killed_any = kill_running_processes || kill_port_processes([3000, 3001]) || cleanup_socket_files
 
           print_kill_summary(killed_any)
         end
@@ -70,11 +74,39 @@ module ReactOnRails
         def terminate_processes(pids)
           pids.each do |pid|
             Process.kill("TERM", pid)
-          rescue StandardError
+          rescue Errno::ESRCH, ArgumentError, RangeError
+            # Process already stopped, or invalid signal/PID - silently skip
+            nil
+          rescue Errno::EPERM
+            # Permission denied - warn the user
+            puts "   ⚠️  Process #{pid} - permission denied (process owned by another user)"
             nil
           end
         end
 
+        def kill_port_processes(ports)
+          killed_any = false
+
+          ports.each do |port|
+            pids = find_port_pids(port)
+            next unless pids.any?
+
+            puts "   ☠️  Killing process on port #{port} (PIDs: #{pids.join(', ')})"
+            terminate_processes(pids)
+            killed_any = true
+          end
+
+          killed_any
+        end
+
+        def find_port_pids(port)
+          stdout, _status = Open3.capture2("lsof", "-ti", ":#{port}", err: File::NULL)
+          stdout.split("\n").map(&:to_i).reject { |pid| pid == Process.pid }
+        rescue StandardError
+          # lsof command not found or other error (permission denied, etc.)
+          []
+        end
+
         def cleanup_socket_files
           files = [".overmind.sock", "tmp/sockets/overmind.sock", "tmp/pids/server.pid"]
           killed_any = false
@@ -116,10 +148,18 @@ module ReactOnRails
           puts help_troubleshooting
         end
 
+        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
         def run_from_command_line(args = ARGV)
           require "optparse"
 
-          options = { route: nil, rails_env: nil }
+          # Get the command early to check for help/kill before running hooks
+          # We need to do this before OptionParser processes flags like -h/--help
+          command = args.find { |arg| !arg.start_with?("--") && !arg.start_with?("-") }
+
+          # Check if help flags are present in args (before OptionParser processes them)
+          help_requested = args.any? { |arg| HELP_FLAGS.include?(arg) }
+
+          options = { route: nil, rails_env: nil, verbose: false }
 
           OptionParser.new do |opts|
             opts.banner = "Usage: dev [command] [options]"
@@ -132,36 +172,125 @@ module ReactOnRails
               options[:rails_env] = env
             end
 
+            opts.on("-v", "--verbose", "Enable verbose output for pack generation") do
+              options[:verbose] = true
+            end
+
             opts.on("-h", "--help", "Prints this help") do
               show_help
               exit
             end
           end.parse!(args)
 
-          # Get the command (anything that's not parsed as an option)
-          command = args[0]
+          # Run precompile hook once before starting any mode (except kill/help)
+          # Then set environment variable to prevent duplicate execution in spawned processes.
+          # Note: We always set SHAKAPACKER_SKIP_PRECOMPILE_HOOK=true (even when no hook is configured)
+          # to provide a consistent signal that bin/dev is managing the precompile lifecycle.
+          # This allows custom scripts to detect bin/dev's presence and adjust behavior accordingly.
+          unless %w[kill help].include?(command) || help_requested
+            run_precompile_hook_if_present
+            ENV["SHAKAPACKER_SKIP_PRECOMPILE_HOOK"] = "true"
+          end
 
           # Main execution
           case command
           when "production-assets", "prod"
-            start(:production_like, nil, verbose: false, route: options[:route], rails_env: options[:rails_env])
+            start(:production_like, nil, verbose: options[:verbose], route: options[:route],
+                                         rails_env: options[:rails_env])
           when "static"
-            start(:static, "Procfile.dev-static-assets", verbose: false, route: options[:route])
+            start(:static, "Procfile.dev-static-assets", verbose: options[:verbose], route: options[:route])
           when "kill"
             kill_processes
-          when "help", "--help", "-h"
+          when "help"
             show_help
           when "hmr", nil
-            start(:development, "Procfile.dev", verbose: false, route: options[:route])
+            start(:development, "Procfile.dev", verbose: options[:verbose], route: options[:route])
           else
             puts "Unknown argument: #{command}"
             puts "Run 'dev help' for usage information"
             exit 1
           end
         end
+        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
 
         private
 
+        def run_precompile_hook_if_present
+          require "open3"
+          require "shellwords"
+
+          hook_value = PackerUtils.shakapacker_precompile_hook_value
+          return unless hook_value
+
+          # Warn if Shakapacker version doesn't support SHAKAPACKER_SKIP_PRECOMPILE_HOOK
+          warn_if_shakapacker_version_too_old
+
+          puts Rainbow("🔧 Running Shakapacker precompile hook...").cyan
+          puts Rainbow("   Command: #{hook_value}").cyan
+          puts ""
+
+          # Capture stdout and stderr for better error reporting
+          # Use Shellwords.split for safer command execution (prevents shell metacharacter interpretation)
+          command_args = Shellwords.split(hook_value.to_s)
+          stdout, stderr, status = Open3.capture3(*command_args)
+
+          if status.success?
+            puts Rainbow("✅ Precompile hook completed successfully").green
+            puts ""
+          else
+            handle_precompile_hook_failure(hook_value, stdout, stderr)
+          end
+        end
+
+        # rubocop:disable Metrics/AbcSize
+        def handle_precompile_hook_failure(hook_value, stdout, stderr)
+          puts ""
+          puts Rainbow("❌ Precompile hook failed!").red.bold
+          puts Rainbow("   Command: #{hook_value}").red
+          puts ""
+
+          if stdout && !stdout.strip.empty?
+            puts Rainbow("   Output:").yellow
+            stdout.strip.split("\n").each { |line| puts Rainbow("   #{line}").yellow }
+            puts ""
+          end
+
+          if stderr && !stderr.strip.empty?
+            puts Rainbow("   Error:").red
+            stderr.strip.split("\n").each { |line| puts Rainbow("   #{line}").red }
+            puts ""
+          end
+
+          puts Rainbow("💡 Fix the hook command in config/shakapacker.yml or remove it to continue").yellow
+          exit 1
+        end
+        # rubocop:enable Metrics/AbcSize
+
+        # rubocop:disable Metrics/AbcSize
+        def warn_if_shakapacker_version_too_old
+          # Only warn for Shakapacker versions in the range 9.0.0 to 9.3.x
+          # Versions below 9.0.0 don't use the precompile_hook feature
+          # Versions 9.4.0+ support SHAKAPACKER_SKIP_PRECOMPILE_HOOK environment variable
+          has_precompile_hook_support = PackerUtils.shakapacker_version_requirement_met?("9.0.0")
+          has_skip_env_var_support = PackerUtils.shakapacker_version_requirement_met?("9.4.0")
+
+          return unless has_precompile_hook_support
+          return if has_skip_env_var_support
+
+          puts ""
+          puts Rainbow("⚠️  Warning: Shakapacker #{PackerUtils.shakapacker_version} detected").yellow.bold
+          puts ""
+          puts Rainbow("   The SHAKAPACKER_SKIP_PRECOMPILE_HOOK environment variable is not").yellow
+          puts Rainbow("   supported in Shakapacker versions below 9.4.0. This may cause the").yellow
+          puts Rainbow("   precompile_hook to run multiple times (once by bin/dev, and again").yellow
+          puts Rainbow("   by each webpack process).").yellow
+          puts ""
+          puts Rainbow("   Recommendation: Upgrade to Shakapacker 9.4.0 or later:").cyan
+          puts Rainbow("   bundle update shakapacker").cyan.bold
+          puts ""
+        end
+        # rubocop:enable Metrics/AbcSize
+
         def help_usage
           Rainbow("📋 Usage: bin/dev [command] [options]").bold
         end
@@ -202,6 +331,7 @@ module ReactOnRails
         end
         # rubocop:enable Metrics/AbcSize
 
+        # rubocop:disable Metrics/AbcSize
         def help_customization
           <<~CUSTOMIZATION
             #{Rainbow('🔧 CUSTOMIZATION:').cyan.bold}
@@ -212,15 +342,31 @@ module ReactOnRails
             #{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
           <<~MODES
             #{Rainbow('🔥 HMR Development mode (default)').cyan.bold} - #{Rainbow('Procfile.dev').green}:
             #{Rainbow('•').yellow} #{Rainbow('Hot Module Replacement (HMR) enabled').white}
-            #{Rainbow('•').yellow} #{Rainbow('React on Rails pack generation before Procfile start').white}
+            #{Rainbow('•').yellow} #{Rainbow('React on Rails pack generation (via precompile hook or bin/dev)').white}
             #{Rainbow('•').yellow} #{Rainbow('Webpack dev server for fast recompilation').white}
             #{Rainbow('•').yellow} #{Rainbow('Source maps for debugging').white}
             #{Rainbow('•').yellow} #{Rainbow('May have Flash of Unstyled Content (FOUC)').white}
@@ -229,7 +375,7 @@ module ReactOnRails
 
             #{Rainbow('📦 Static development mode').cyan.bold} - #{Rainbow('Procfile.dev-static-assets').green}:
             #{Rainbow('•').yellow} #{Rainbow('No HMR (static assets with auto-recompilation)').white}
-            #{Rainbow('•').yellow} #{Rainbow('React on Rails pack generation before Procfile start').white}
+            #{Rainbow('•').yellow} #{Rainbow('React on Rails pack generation (via precompile hook or bin/dev)').white}
             #{Rainbow('•').yellow} #{Rainbow('Webpack watch mode for auto-recompilation').white}
             #{Rainbow('•').yellow} #{Rainbow('CSS extracted to separate files (no FOUC)').white}
             #{Rainbow('•').yellow} #{Rainbow('Development environment (faster builds than production)').white}
@@ -237,7 +383,7 @@ module ReactOnRails
             #{Rainbow('•').yellow} #{Rainbow('Access at:').white} #{Rainbow('http://localhost:3000/<route>').cyan.underline}
 
             #{Rainbow('🏭 Production-assets mode').cyan.bold} - #{Rainbow('Procfile.dev-prod-assets').green}:
-            #{Rainbow('•').yellow} #{Rainbow('React on Rails pack generation before Procfile start').white}
+            #{Rainbow('•').yellow} #{Rainbow('React on Rails pack generation (via precompile hook or assets:precompile)').white}
             #{Rainbow('•').yellow} #{Rainbow('Asset precompilation with NODE_ENV=production (webpack optimizations)').white}
             #{Rainbow('•').yellow} #{Rainbow('RAILS_ENV=development by default for assets:precompile (avoids credentials)').white}
             #{Rainbow('•').yellow} #{Rainbow('Use --rails-env=production for assets:precompile only (not server processes)').white}
@@ -253,16 +399,24 @@ module ReactOnRails
         def run_production_like(_verbose: false, route: nil, rails_env: nil)
           procfile = "Procfile.dev-prod-assets"
 
+          features = [
+            "Precompiling assets with production optimizations",
+            "Running Rails server on port 3001",
+            "No HMR (Hot Module Replacement)",
+            "CSS extracted to separate files (no FOUC)"
+          ]
+
+          # NOTE: Pack generation happens automatically during assets:precompile
+          # 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...",
-            [
-              "Generating React on Rails packs",
-              "Precompiling assets with production optimizations",
-              "Running Rails server on port 3001",
-              "No HMR (Hot Module Replacement)",
-              "CSS extracted to separate files (no FOUC)"
-            ],
+            features,
             3001,
             route: route
           )
@@ -381,15 +535,25 @@ module ReactOnRails
 
         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)",
+            "Development environment (source maps, faster builds)",
+            "Auto-recompiles on file changes"
+          ]
+
+          # Add pack generation info if not using precompile hook
+          unless ReactOnRails::PackerUtils.shakapacker_precompile_hook_configured?
+            features.unshift("Generating React on Rails packs")
+          end
+
           print_server_info(
             "⚡ Starting development server with static assets...",
-            [
-              "Generating React on Rails packs",
-              "Using shakapacker --watch (no HMR)",
-              "CSS extracted to separate files (no FOUC)",
-              "Development environment (source maps, faster builds)",
-              "Auto-recompiles on file changes"
-            ],
+            features,
             route: route
           )
 
@@ -400,6 +564,10 @@ module ReactOnRails
 
         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)

data/lib/react_on_rails/dev/service_checker.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "English"
+require "rainbow"
+
+module ReactOnRails
+  module Dev
+    # ServiceChecker validates that required external services are running
+    # before starting the development server.
+    #
+    # Configuration is read from .dev-services.yml in the app root:
+    #
+    # services:
+    #   redis:
+    #     check_command: "redis-cli ping"
+    #     expected_output: "PONG"
+    #     start_command: "redis-server"
+    #     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"
+    #
+    class ServiceChecker
+      # Configuration file keys
+      CONFIG_KEYS = {
+        services: "services",
+        check_command: "check_command",
+        expected_output: "expected_output",
+        start_command: "start_command",
+        install_hint: "install_hint",
+        description: "description"
+      }.freeze
+
+      class << self
+        # Check all required services and provide helpful output
+        #
+        # @param config_path [String] Path to .dev-services.yml (default: ./.dev-services.yml)
+        # @return [Boolean] true if all services are running or no config exists
+        def check_services(config_path: ".dev-services.yml")
+          return true unless File.exist?(config_path)
+
+          config = load_config(config_path)
+          return true unless config_has_services?(config)
+
+          check_and_report_services(config, config_path)
+        end
+
+        private
+
+        def config_has_services?(config)
+          config &&
+            config[CONFIG_KEYS[:services]].is_a?(Hash) &&
+            !config[CONFIG_KEYS[:services]].empty?
+        end
+
+        def check_and_report_services(config, config_path)
+          print_services_header(config_path)
+
+          failures = collect_service_failures(config[CONFIG_KEYS[:services]])
+
+          report_results(failures)
+        end
+
+        def collect_service_failures(services)
+          failures = []
+
+          services.each do |name, service_config|
+            if check_service(name, service_config)
+              print_service_ok(name, service_config[CONFIG_KEYS[:description]])
+            else
+              failures << { name: name, config: service_config }
+              print_service_failed(name, service_config[CONFIG_KEYS[:description]])
+            end
+          end
+
+          failures
+        end
+
+        def report_results(failures)
+          if failures.empty?
+            print_all_services_ok
+            true
+          else
+            print_failures_summary(failures)
+            false
+          end
+        end
+
+        def load_config(config_path)
+          YAML.load_file(config_path)
+        rescue StandardError => e
+          puts Rainbow("⚠️  Failed to load #{config_path}: #{e.message}").yellow
+          puts Rainbow("   Continuing without service checks...").yellow
+          puts ""
+          nil
+        end
+
+        def check_service(_name, config)
+          check_command = config[CONFIG_KEYS[:check_command]]
+          expected_output = config[CONFIG_KEYS[:expected_output]]
+
+          return false if check_command.nil?
+
+          output, status = run_check_command(check_command)
+
+          return false if status.nil?
+
+          return status.success? if expected_output.nil?
+
+          # Safe nil check for output before calling include?
+          status.success? && output&.include?(expected_output)
+        end
+
+        def run_check_command(command)
+          require "open3"
+          # Execute command as-is. Commands are from local .dev-services.yml config file
+          # which should be trusted. Shell metacharacters won't work as expected since
+          # Open3.capture3 doesn't invoke a shell by default for simple command strings.
+          stdout, stderr, status = Open3.capture3(command, err: %i[child out])
+          output = stdout + stderr
+          [output, status]
+        rescue Errno::ENOENT
+          # Command not found - service is not available
+          ["", nil]
+        rescue ArgumentError => e
+          # Invalid command format
+          warn "Invalid command format: #{e.message}" if ENV["DEBUG"]
+          ["", nil]
+        rescue StandardError => e
+          # Log unexpected errors for debugging
+          warn "Unexpected error checking service: #{e.message}" if ENV["DEBUG"]
+          ["", nil]
+        end
+
+        def print_services_header(config_path)
+          puts ""
+          puts Rainbow("🔍 Checking required services (#{config_path})...").cyan.bold
+          puts ""
+        end
+
+        def print_service_ok(name, description)
+          desc = description ? " - #{description}" : ""
+          puts "   #{Rainbow('✓').green} #{name}#{desc}"
+        end
+
+        def print_service_failed(name, description)
+          desc = description ? " - #{description}" : ""
+          puts "   #{Rainbow('✗').red} #{name}#{desc}"
+        end
+
+        def print_all_services_ok
+          puts ""
+          puts Rainbow("✅ All services are running").green.bold
+          puts ""
+        end
+
+        # rubocop:disable Metrics/AbcSize
+        def print_failures_summary(failures)
+          puts ""
+          puts Rainbow("❌ Some services are not running").red.bold
+          puts ""
+          puts Rainbow("Please start these services before running bin/dev:").yellow
+          puts ""
+
+          failures.each do |failure|
+            name = failure[:name]
+            config = failure[:config]
+            description = config[CONFIG_KEYS[:description]] || name
+
+            puts Rainbow(name.to_s).cyan.bold
+            puts "   #{description}" if config[CONFIG_KEYS[:description]]
+
+            if config[CONFIG_KEYS[:start_command]]
+              puts ""
+              puts "   #{Rainbow('To start:').yellow}"
+              puts "   #{Rainbow(config[CONFIG_KEYS[:start_command]]).green}"
+            end
+
+            if config[CONFIG_KEYS[:install_hint]]
+              puts ""
+              puts "   #{Rainbow('Not installed?').yellow} #{config[CONFIG_KEYS[:install_hint]]}"
+            end
+
+            puts ""
+          end
+
+          puts Rainbow("💡 Tips:").blue.bold
+          puts "   • Start services manually, then run bin/dev again"
+          puts "   • Or remove service from .dev-services.yml if not needed"
+          puts "   • Or add service to Procfile.dev to start automatically"
+          puts ""
+        end
+        # rubocop:enable Metrics/AbcSize
+      end
+    end
+  end
+end