shakapacker 9.2.0 → 9.3.0.beta.0

data/lib/install/config/shakapacker.yml

@@ -43,11 +43,22 @@ default: &default
   # Select JavaScript transpiler to use
   # Available options: 'swc' (default, 20x faster), 'babel', or 'esbuild'
   # Note: When using rspack, swc is used automatically regardless of this setting
-  javascript_transpiler: 'swc'
+  javascript_transpiler: "swc"
 
   # Select assets bundler to use
   # Available options: 'webpack' (default) or 'rspack'
-  assets_bundler: 'webpack'
+  assets_bundler: "webpack"
+
+  # Path to the directory containing webpack/rspack config files
+  # Defaults to 'config/webpack' for webpack or 'config/rspack' for rspack
+  # Use '.' to specify the root directory of your project
+  # assets_bundler_config_path: config/webpack
+
+  # Hook to run before webpack compilation (e.g., for generating dynamic entry points)
+  # SECURITY: Only reference trusted scripts within your project. The hook command will be
+  # validated to ensure it points to a file within the project root.
+  # Example: precompile_hook: 'bin/shakapacker-precompile-hook'
+  # precompile_hook: ~
 
   # Raises an error if there is a mismatch in the shakapacker gem and npm package being used
   ensure_consistent_versioning: true
@@ -112,14 +123,14 @@ development:
     # Should we use gzip compression?
     compress: true
     # Note that apps that do not check the host are vulnerable to DNS rebinding attacks
-    allowed_hosts: 'auto'
+    allowed_hosts: "auto"
     # Shows progress and colorizes output of bin/shakapacker[-dev-server]
     pretty: true
     headers:
-      'Access-Control-Allow-Origin': '*'
+      "Access-Control-Allow-Origin": "*"
     static:
       watch:
-        ignored: '**/node_modules/**'
+        ignored: "**/node_modules/**"
 
 test:
   <<: *default

data/lib/shakapacker/compiler.rb

@@ -1,5 +1,6 @@
 require "open3"
 require "fileutils"
+require "shellwords"
 
 require_relative "compiler_strategy"
 
@@ -26,6 +27,7 @@ class Shakapacker::Compiler
       true
     else
       acquire_ipc_lock do
+        run_precompile_hook if config.precompile_hook
         run_webpack.tap do |success|
           after_compile_hook
         end
@@ -78,6 +80,84 @@ class Shakapacker::Compiler
       /ruby/.match?(first_line) ? RbConfig.ruby : ""
     end
 
+    def run_precompile_hook
+      hook_command = config.precompile_hook
+      hook_spec = validate_precompile_hook(hook_command)
+
+      logger.info "Running precompile hook: #{hook_command}"
+
+      runtime_env = webpack_env.merge(hook_spec[:env])
+      stdout, stderr, status = Open3.capture3(
+        runtime_env,
+        hook_spec[:executable],
+        *hook_spec[:args],
+        chdir: File.expand_path(config.root_path)
+      )
+
+      if status.success?
+        logger.info "Precompile hook completed successfully"
+        logger.info stdout unless stdout.empty?
+        logger.warn stderr unless stderr.empty?
+      else
+        non_empty_streams = [stdout, stderr].delete_if(&:empty?)
+        logger.error "\nPRECOMPILE HOOK FAILED:\nEXIT STATUS: #{status.exitstatus}\nCOMMAND: #{hook_command}\nOUTPUTS:\n#{non_empty_streams.join("\n\n")}"
+        logger.error "\nTo fix this:"
+        logger.error "  1. Check that the hook script exists and is executable"
+        logger.error "  2. Test the hook command manually: #{hook_command}"
+        logger.error "  3. Review the error output above for details"
+        logger.error "  4. You can disable the hook temporarily by commenting out 'precompile_hook' in shakapacker.yml"
+        raise "Precompile hook '#{hook_command}' failed with exit status #{status.exitstatus}"
+      end
+    end
+
+    def validate_precompile_hook(hook_command)
+      hook_tokens = begin
+        Shellwords.shellsplit(hook_command)
+      rescue ArgumentError => e
+        raise "Shakapacker configuration error: Invalid precompile_hook command syntax: #{e.message}. Check for unmatched quotes in: #{hook_command}"
+      end
+
+      env_assignments = {}
+      while hook_tokens.first&.match?(/\A[A-Za-z_][A-Za-z0-9_]*=/)
+        key, value = hook_tokens.shift.split("=", 2)
+        env_assignments[key] = value
+      end
+
+      executable = hook_tokens.shift
+      if executable.nil? || executable.empty?
+        raise "Shakapacker configuration error: precompile_hook must include an executable command. Got: #{hook_command}"
+      end
+
+      executable_path = config.root_path.join(executable)
+
+      # Security: Resolve symlinks and verify the hook points to a file within the project
+      # This prevents symlink bypass attacks and path traversal attacks
+      begin
+        resolved_path = executable_path.realpath
+        resolved_root = config.root_path.realpath
+      rescue Errno::ENOENT
+        # If file doesn't exist, use cleanpath for basic validation
+        resolved_path = executable_path.cleanpath
+        resolved_root = config.root_path.cleanpath
+      end
+
+      # Verify path is within project root with proper separator check
+      # Using File::SEPARATOR prevents partial path matches (e.g., /project vs /project-evil)
+      unless resolved_path.to_s.start_with?(resolved_root.to_s + File::SEPARATOR)
+        raise "Security Error: precompile_hook must reference a script within the project root. " \
+              "Got: #{hook_command} (resolved to: #{resolved_path})"
+      end
+
+      # Warn if the executable doesn't exist within the project
+      unless File.exist?(executable_path)
+        logger.warn "⚠️  Warning: precompile_hook executable not found: #{executable_path}"
+        logger.warn "   The hook command is configured but the script does not exist within the project root."
+        logger.warn "   Please ensure the script exists or remove 'precompile_hook' from your shakapacker.yml configuration."
+      end
+
+      { env: env_assignments, executable: executable, args: hook_tokens }
+    end
+
     def run_webpack
       logger.info "Compiling..."
 

data/lib/shakapacker/configuration.rb

@@ -117,6 +117,17 @@ class Shakapacker::Configuration
     assets_bundler == "webpack"
   end
 
+  def precompile_hook
+    hook = fetch(:precompile_hook)
+    return nil if hook.nil? || (hook.is_a?(String) && hook.strip.empty?)
+
+    unless hook.is_a?(String)
+      raise "Shakapacker configuration error: precompile_hook must be a string, got #{hook.class}"
+    end
+
+    hook.strip
+  end
+
   def javascript_transpiler
     # Show deprecation warning if using old 'webpack_loader' key
     if data.has_key?(:webpack_loader) && !data.has_key?(:javascript_transpiler)
@@ -137,6 +148,14 @@ class Shakapacker::Configuration
     javascript_transpiler
   end
 
+  def assets_bundler_config_path
+    custom_path = fetch(:assets_bundler_config_path)
+    return custom_path if custom_path
+
+    # Default paths based on bundler type
+    rspack? ? "config/rspack" : "config/webpack"
+  end
+
   private
 
     def default_javascript_transpiler
@@ -308,11 +327,20 @@ class Shakapacker::Configuration
     end
 
     def log_fallback(requested_env, fallback_env)
-      return unless Shakapacker.logger
+      message = "Shakapacker environment '#{requested_env}' not found in #{config_path}, " \
+                "falling back to '#{fallback_env}'"
 
-      Shakapacker.logger.info(
-        "Shakapacker environment '#{requested_env}' not found in #{config_path}, " \
-        "falling back to '#{fallback_env}'"
-      )
+      # Try to use the logger if available, otherwise fall back to stdout
+      begin
+        if Shakapacker.respond_to?(:logger) && Shakapacker.logger
+          Shakapacker.logger.info(message)
+        else
+          puts message
+        end
+      rescue NameError, NoMethodError
+        # If logger access fails (e.g., circular dependency in standalone runner context),
+        # fall back to stdout so the message still gets displayed
+        puts message
+      end
     end
 end

data/lib/shakapacker/dev_server_runner.rb

@@ -4,13 +4,150 @@ require "socket"
 require_relative "configuration"
 require_relative "dev_server"
 require_relative "runner"
+require_relative "version"
 
 module Shakapacker
   class DevServerRunner < Shakapacker::Runner
     def self.run(argv)
+      # Show Shakapacker help and exit (don't call bundler)
+      if argv.include?("--help") || argv.include?("-h")
+        print_help
+        exit(0)
+      elsif argv.include?("--version") || argv.include?("-v")
+        print_version
+        exit(0)
+      end
+
       new(argv).run
     end
 
+    def self.print_help
+      puts <<~HELP
+        ================================================================================
+        SHAKAPACKER DEV SERVER - Development Server with Hot Module Replacement
+        ================================================================================
+
+        Usage: bin/shakapacker-dev-server [options]
+
+        Shakapacker-specific options:
+          -h, --help              Show this help message
+          -v, --version           Show Shakapacker version
+          --debug-shakapacker     Enable Node.js debugging (--inspect-brk)
+
+        Examples:
+          bin/shakapacker-dev-server                    # Start dev server
+          bin/shakapacker-dev-server --no-hot           # Disable HMR
+          bin/shakapacker-dev-server --open             # Open browser automatically
+          bin/shakapacker-dev-server --debug-shakapacker # Debug with Node inspector
+
+      HELP
+
+      print_dev_server_help
+
+      puts <<~HELP
+
+        Options managed by Shakapacker (configured in config/shakapacker.yml):
+          --host                  Set from dev_server.host (default: localhost)
+          --port                  Set from dev_server.port (default: 3035)
+          --https                 Set from dev_server.server (http or https)
+          --config                Set automatically to config/webpack/webpack.config.js
+                                  or config/rspack/rspack.config.js
+
+        Note: CLI flags for --host, --port, and --https are NOT supported.
+        Configure these in config/shakapacker.yml instead.
+      HELP
+    end
+
+    def self.print_dev_server_help
+      bundler_type, bundler_help = get_dev_server_help
+
+      if bundler_help
+        bundler_name = bundler_type == :rspack ? "RSPACK" : "WEBPACK"
+        puts "=" * 80
+        puts "AVAILABLE #{bundler_name} DEV SERVER OPTIONS (Passed directly to #{bundler_name.downcase})"
+        puts "=" * 80
+        puts
+        puts filter_managed_options(bundler_help)
+        puts
+        puts "For complete documentation:"
+        if bundler_type == :rspack
+          puts "  https://rspack.dev/config/dev-server"
+        else
+          puts "  https://webpack.js.org/configuration/dev-server/"
+        end
+      else
+        puts "For complete documentation:"
+        puts "  Webpack: https://webpack.js.org/configuration/dev-server/"
+        puts "  Rspack:  https://rspack.dev/config/dev-server"
+      end
+    end
+
+    def self.get_dev_server_help
+      Runner.execute_bundler_command("serve", "--help") { |stdout| stdout }
+    end
+
+    # Filter dev server help output to remove Shakapacker-managed options
+    #
+    # This method processes the raw help output from webpack-dev-server/rspack serve
+    # and removes options that Shakapacker manages automatically:
+    # - --config (set from config/webpack or config/rspack)
+    # - --host, --port (set from config/shakapacker.yml dev_server settings)
+    # - --help, --version (shown separately in Shakapacker's help)
+    #
+    # The filtering uses skip_until_blank to track multi-line option descriptions
+    # and skip them entirely when the option header matches a managed option.
+    #
+    # Note: This relies on dev server help format conventions. If webpack-dev-server
+    # or rspack significantly changes their help output format, this may need adjustment.
+    def self.filter_managed_options(help_text)
+      lines = help_text.lines
+      filtered_lines = []
+      skip_until_blank = false
+
+      lines.each do |line|
+        # Skip options that Shakapacker manages and their descriptions
+        # These options are shown in the "Options managed by Shakapacker" section
+        if line.match?(/^\s*(-c,\s*)?--config\b/) ||
+           line.match?(/^\s*--configName\b/) ||
+           line.match?(/^\s*--configLoader\b/) ||
+           line.match?(/^\s*--nodeEnv\b/) ||
+           line.match?(/^\s*--host\b/) ||
+           line.match?(/^\s*--port\b/) ||
+           line.match?(/^\s*--https\b/) ||
+           line.match?(/^\s*(-h,\s*)?--help\b/) ||
+           line.match?(/^\s*(-v,\s*)?--version\b/)
+          skip_until_blank = true
+          next
+        end
+
+        # Continue skipping lines that are part of a filtered option's description
+        # Reset when we hit a blank line or the start of a new option (starts with -)
+        if skip_until_blank
+          if line.strip.empty? || line.match?(/^\s*-/)
+            skip_until_blank = false
+          else
+            next
+          end
+        end
+
+        filtered_lines << line
+      end
+
+      filtered_lines.join
+    end
+
+    def self.print_version
+      puts "Shakapacker #{Shakapacker::VERSION}"
+      puts "Framework: Rails #{Rails.version}" if defined?(Rails)
+
+      # Try to get bundler version
+      bundler_type, bundler_version = Runner.get_bundler_version
+      if bundler_version
+        bundler_name = bundler_type == :rspack ? "Rspack" : "Webpack"
+        puts "Bundler: #{bundler_name} #{bundler_version}"
+      end
+    end
+
     def run
       load_config
       detect_unsupported_switches!
@@ -96,8 +233,10 @@ module Shakapacker
         cmd += @argv
 
         Dir.chdir(@app_path) do
-          Kernel.exec env, *cmd
+          system(env, *cmd)
         end
+
+        exit($?.exitstatus || 1) unless $?.success?
       end
 
       def build_cmd