react_on_rails 16.1.2 → 16.2.0

data/lib/react_on_rails/dev/pack_generator.rb

@@ -1,26 +1,192 @@
 # frozen_string_literal: true
 
 require "English"
+require "stringio"
+require_relative "../packer_utils"
 
 module ReactOnRails
   module Dev
+    # PackGenerator triggers the generation of React on Rails packs
+    #
+    # Design decisions:
+    # 1. Why trigger via Rake task instead of direct Ruby code?
+    #    - The actual pack generation logic lives in lib/react_on_rails/packs_generator.rb
+    #    - The rake task (lib/tasks/generate_packs.rake) provides a stable, documented interface
+    #    - This allows the implementation to evolve without breaking bin/dev
+    #    - Users can also run the task directly: `rake react_on_rails:generate_packs`
+    #
+    # 2. Why two execution strategies (direct vs bundle exec)?
+    #    - Direct Rake execution: Faster when already in Bundler/Rails context (bin/dev)
+    #    - Bundle exec fallback: Required when called outside Rails context
+    #    - This optimization avoids subprocess overhead in the common case
+    #
+    # 3. Why is the class named "PackGenerator" when it delegates?
+    #    - It's a semantic wrapper around pack generation for the dev workflow
+    #    - Provides a clean API for bin/dev without exposing Rake internals
+    #    - Handles hook detection, error handling, and output formatting
     class PackGenerator
       class << self
         def generate(verbose: false)
+          # Skip if shakapacker has a precompile hook configured
+          if ReactOnRails::PackerUtils.shakapacker_precompile_hook_configured?
+            if verbose
+              hook_value = ReactOnRails::PackerUtils.shakapacker_precompile_hook_value
+              puts "⏭️  Skipping pack generation (handled by shakapacker precompile hook: #{hook_value})"
+            end
+            return
+          end
+
           if verbose
             puts "📦 Generating React on Rails packs..."
-            success = system "bundle exec rake react_on_rails:generate_packs"
+            success = run_pack_generation(silent: false, verbose: true)
           else
             print "📦 Generating packs... "
-            success = system "bundle exec rake react_on_rails:generate_packs > /dev/null 2>&1"
+            success = run_pack_generation(silent: true, verbose: false)
             puts success ? "✅" : "❌"
           end
 
           return if success
 
           puts "❌ Pack generation failed"
+          unless verbose
+            puts ""
+            puts "💡 Run with #{Rainbow('--verbose').cyan.bold} flag for detailed output:"
+            puts "   #{Rainbow('bin/dev --verbose').green.bold}"
+          end
           exit 1
         end
+
+        private
+
+        def run_pack_generation(silent: false, verbose: false)
+          # Set environment variable for child processes to respect verbose mode
+          ENV["REACT_ON_RAILS_VERBOSE"] = verbose ? "true" : "false"
+
+          # If we're already inside a Bundler context AND Rails is available (e.g., called from bin/dev),
+          # we can directly require and run the task. Otherwise, use bundle exec.
+          if should_run_directly?
+            run_rake_task_directly(silent: silent)
+          else
+            run_via_bundle_exec(silent: silent, verbose: verbose)
+          end
+        ensure
+          # Clean up environment variable
+          ENV.delete("REACT_ON_RAILS_VERBOSE")
+        end
+
+        def should_run_directly?
+          # Check if we're in a meaningful Bundler context with BUNDLE_GEMFILE
+          return false unless defined?(Bundler)
+          return false unless ENV["BUNDLE_GEMFILE"]
+          return false unless rails_available?
+
+          true
+        end
+
+        def rails_available?
+          return false unless defined?(Rails)
+          return false unless Rails.respond_to?(:application)
+          return false if Rails.application.nil?
+
+          # Verify Rails app can actually load tasks
+          begin
+            Rails.application.respond_to?(:load_tasks)
+          rescue StandardError
+            false
+          end
+        end
+
+        def run_rake_task_directly(silent: false)
+          require "rake"
+
+          load_rake_tasks
+          task = prepare_rake_task
+
+          capture_output(silent) do
+            task.invoke
+            true
+          end
+        rescue StandardError => e
+          handle_rake_error(e, silent)
+          false
+        end
+
+        def load_rake_tasks
+          return if Rake::Task.task_defined?("react_on_rails:generate_packs")
+
+          Rails.application.load_tasks
+        end
+
+        def prepare_rake_task
+          task = Rake::Task["react_on_rails:generate_packs"]
+          task.reenable # Allow re-execution if called multiple times
+          task
+        end
+
+        def capture_output(silent)
+          return yield unless silent
+
+          original_stdout = $stdout
+          original_stderr = $stderr
+          output_buffer = StringIO.new
+          $stdout = output_buffer
+          $stderr = output_buffer
+
+          begin
+            yield
+          ensure
+            $stdout = original_stdout
+            $stderr = original_stderr
+          end
+        end
+
+        def handle_rake_error(error, _silent)
+          error_msg = "Error generating packs: #{error.message}"
+          error_msg += "\n#{error.backtrace.join("\n")}" if ENV["DEBUG"]
+
+          # Always write to stderr, even in silent mode
+          # Use STDERR constant instead of warn/$stderr to bypass capture_output redirection
+          # rubocop:disable Style/StderrPuts, Style/GlobalStdStream
+          STDERR.puts error_msg
+          # rubocop:enable Style/StderrPuts, Style/GlobalStdStream
+        end
+
+        def run_via_bundle_exec(silent: false, verbose: false)
+          # Environment variable is already set in run_pack_generation, but we make it explicit here
+          # for clarity and to ensure it's passed to the subprocess
+          env = { "REACT_ON_RAILS_VERBOSE" => verbose ? "true" : "false" }
+
+          # Need to unbundle to prevent Bundler from intercepting our bundle exec call
+          # when already running inside a Bundler context (e.g., from bin/dev)
+          with_unbundled_context do
+            if silent
+              system(
+                env,
+                "bundle", "exec", "rake", "react_on_rails:generate_packs",
+                out: File::NULL, err: File::NULL
+              )
+            else
+              system(env, "bundle", "exec", "rake", "react_on_rails:generate_packs")
+            end
+          end
+        end
+
+        # DRY helper method for Bundler context switching with API compatibility
+        # Supports both new (with_unbundled_env) and legacy (with_clean_env) Bundler APIs
+        def with_unbundled_context(&block)
+          if defined?(Bundler)
+            if Bundler.respond_to?(:with_unbundled_env)
+              Bundler.with_unbundled_env(&block)
+            elsif Bundler.respond_to?(:with_clean_env)
+              Bundler.with_clean_env(&block)
+            else
+              # Fallback if neither method is available (very old Bundler versions)
+              yield
+            end
+          else
+            yield
+          end
+        end
       end
     end
   end

data/lib/react_on_rails/dev/process_manager.rb

@@ -1,14 +1,18 @@
 # frozen_string_literal: true
 
+require "timeout"
+
 module ReactOnRails
   module Dev
     class ProcessManager
+      # Timeout for version check operations to prevent hanging
+      VERSION_CHECK_TIMEOUT = 5
+
       class << self
+        # Check if a process is available and usable in the current execution context
+        # This accounts for bundler context where system commands might be intercepted
         def installed?(process)
-          IO.popen([process, "-v"], &:close)
-          true
-        rescue Errno::ENOENT
-          false
+          installed_in_current_context?(process)
         end
 
         def ensure_procfile(procfile)
@@ -31,20 +35,138 @@ module ReactOnRails
           # Clean up stale files before starting
           FileManager.cleanup_stale_files
 
-          if installed?("overmind")
-            system("overmind", "start", "-f", procfile)
-          elsif installed?("foreman")
-            system("foreman", "start", "-f", procfile)
+          # Try process managers in order of preference
+          # run_process_if_available returns:
+          #   - true/false (exit status) if process was found and executed
+          #   - nil if process was not found
+          overmind_result = run_process_if_available("overmind", ["start", "-f", procfile])
+          return if overmind_result == true # Overmind ran successfully
+
+          foreman_result = run_process_if_available("foreman", ["start", "-f", procfile])
+          return if foreman_result == true # Foreman ran successfully
+
+          # If either process was found but exited with error, don't show "not found" message
+          # The process manager itself will have shown its own error message
+          exit 1 if overmind_result == false || foreman_result == false
+
+          # Neither process manager was found
+          show_process_manager_installation_help
+          exit 1
+        end
+
+        private
+
+        # Check if a process is actually usable in the current execution context
+        # This is important for commands that might be intercepted by bundler
+        def installed_in_current_context?(process)
+          # Try to execute the process with version flags to see if it works
+          # Use system() because that's how we'll actually call it later
+          version_flags_for(process).any? do |flag|
+            # Add timeout to prevent hanging on version checks
+            Timeout.timeout(VERSION_CHECK_TIMEOUT) do
+              system(process, flag, out: File::NULL, err: File::NULL)
+            end
+          end
+        rescue Errno::ENOENT, Timeout::Error
+          false
+        end
+
+        # Get appropriate version flags for different processes
+        def version_flags_for(process)
+          case process
+          when "overmind"
+            ["--version"]
+          when "foreman"
+            ["--version", "-v"]
           else
-            warn <<~MSG
-              NOTICE:
-              For this script to run, you need either 'overmind' or 'foreman' installed on your machine. Please try this script after installing one of them.
-            MSG
-            exit 1
+            ["--version", "-v", "-V"]
           end
         end
 
-        private
+        # Try to run a process if it's available, with intelligent fallback strategy
+        # Returns:
+        #   - true if process ran and exited successfully (exit code 0)
+        #   - false if process ran but exited with error (non-zero exit code)
+        #   - nil if process was not found/available
+        def run_process_if_available(process, args)
+          # First attempt: try in current context (works for bundled processes)
+          return system(process, *args) if installed?(process)
+
+          # Second attempt: try in system context (works for system-installed processes)
+          return run_process_outside_bundle(process, args) if process_available_in_system?(process)
+
+          # Process not available in either context
+          nil
+        end
+
+        # Run a process outside of bundler context
+        # This allows using system-installed processes even when they're not in the Gemfile
+        def run_process_outside_bundle(process, args)
+          if defined?(Bundler)
+            with_unbundled_context do
+              system(process, *args)
+            end
+          else
+            # Fallback if Bundler is not available
+            system(process, *args)
+          end
+        end
+
+        # Check if a process is available system-wide (outside bundle context)
+        def process_available_in_system?(process)
+          return false unless defined?(Bundler)
+
+          with_unbundled_context do
+            # Try version flags to check if process exists outside bundler context
+            version_flags_for(process).any? do |flag|
+              # Add timeout to prevent hanging on version checks
+              Timeout.timeout(VERSION_CHECK_TIMEOUT) do
+                system(process, flag, out: File::NULL, err: File::NULL)
+              end
+            end
+          end
+        rescue Errno::ENOENT, Timeout::Error
+          false
+        end
+
+        # DRY helper method for Bundler context switching with API compatibility
+        # Supports both new (with_unbundled_env) and legacy (with_clean_env) Bundler APIs
+        def with_unbundled_context(&block)
+          if Bundler.respond_to?(:with_unbundled_env)
+            Bundler.with_unbundled_env(&block)
+          elsif Bundler.respond_to?(:with_clean_env)
+            Bundler.with_clean_env(&block)
+          else
+            # Fallback if neither method is available (very old Bundler versions)
+            yield
+          end
+        end
+
+        # Improved error message with helpful guidance
+        def show_process_manager_installation_help
+          warn <<~MSG
+            ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+            ERROR: Process Manager Not Found
+            ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+            To run the React on Rails development server, you need either 'overmind' or
+            'foreman' installed on your system.
+
+            RECOMMENDED INSTALLATION:
+
+              macOS:    brew install overmind
+              Linux:    gem install foreman
+
+            IMPORTANT:
+            DO NOT add foreman to your Gemfile. Install it globally on your system.
+
+            For more information about why foreman should not be in your Gemfile, see:
+            https://github.com/ddollar/foreman/wiki/Don't-Bundle-Foreman
+
+            After installation, try running this script again.
+            ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+          MSG
+        end
 
         def valid_procfile_path?(procfile)
           # Reject paths with shell metacharacters