shakacode
diff --git a/‎CHANGELOG.md‎
Lines changed: 10 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 10 additions & 0 deletions
diff --git a/‎docs/contributor-info/releasing.md‎
Lines changed: 126 additions & 17 deletions b/‎docs/contributor-info/releasing.md‎
Lines changed: 126 additions & 17 deletions
diff --git a/‎lib/react_on_rails/engine.rb‎
Lines changed: 10 additions & 1 deletion b/‎lib/react_on_rails/engine.rb‎
Lines changed: 10 additions & 1 deletion
diff --git a/‎lib/react_on_rails/utils.rb‎
Lines changed: 120 additions & 0 deletions b/‎lib/react_on_rails/utils.rb‎
Lines changed: 120 additions & 0 deletions
@@ -27,6 +27,8 @@ Changes since the last non-beta release.
 
 - **Attribution Comment**: Added HTML comment attribution to Rails views containing React on Rails functionality. The comment automatically displays which version is in use (open source React on Rails or React on Rails Pro) and, for Pro users, shows the license status. This helps identify React on Rails usage across your application. [PR #1857](https://github.com/shakacode/react_on_rails/pull/1857) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
 
+- **Improved Error Messages**: Error messages for version mismatches and package configuration issues now include package-manager-specific installation commands (npm, yarn, pnpm, bun). [PR #1881](https://github.com/shakacode/react_on_rails/pull/1881) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
+
 #### Breaking Changes
 
 - **React on Rails Core Package**: Several Pro-only methods have been removed from the core package and are now exclusively available in the `react-on-rails-pro` package. If you're using any of the following methods, you'll need to migrate to React on Rails Pro:
@@ -106,6 +108,14 @@ To migrate to React on Rails Pro:
 
   These helpers are now defined exclusively in the `react-on-rails-pro` gem.
 
+- **Strict Version Validation at Boot Time**: Applications now fail to boot (instead of logging warnings) when package.json is misconfigured with wrong versions, missing packages, or semver wildcards. Users must use exact versions in package.json (no ^, ~, >, <, \* operators). **Migration**: Update package.json to use exact versions matching installed gem (e.g., `"16.1.1"` not `"^16.1.1"`). [PR #1881](https://github.com/shakacode/react_on_rails/pull/1881) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
+
+- **Node Renderer Version Validation** (Pro users only): Remote node renderer now validates gem version at request time. Version mismatches in development return 412 Precondition Failed (production allows with warning). **Migration**: Ensure react_on_rails_pro gem and @shakacode-tools/react-on-rails-pro-node-renderer package versions match. [PR #1881](https://github.com/shakacode/react_on_rails/pull/1881) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
+
+#### Security
+
+- **Command Injection Protection**: Added security hardening to prevent potential command injection in package manager commands. [PR #1881](https://github.com/shakacode/react_on_rails/pull/1881) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
+
 ### [16.1.1] - 2025-09-24
 
 #### Bug Fixes
 
@@ -1,6 +1,6 @@
 # Install and Release
 
-We're releasing this as a combined Ruby gem plus two NPM packages. We keep the version numbers in sync across all packages.
+We're releasing this as a unified release with 5 packages total. We keep the version numbers in sync across all packages using unified versioning.
 
 ## Testing the Gem before Release from a Rails App
 
@@ -13,41 +13,79 @@ Run `rake -D release` to see instructions on how to release via the rake task.
 ### Release Command
 
 ```bash
-rake release[gem_version,dry_run]
+rake release[version,dry_run,registry,skip_push]
 ```
 
 **Arguments:**
 
-- `gem_version`: The new version in rubygem format (no dashes). Pass no argument to automatically perform a patch version bump.
-- `dry_run`: Optional. Pass `true` to see what would happen without actually releasing.
+1. **`version`** (required): Version bump type or explicit version
 
-**Example:**
+   - Bump types: `patch`, `minor`, `major`
+   - Explicit: `16.2.0`
+   - Pre-release: `16.2.0.beta.1` (rubygem format with dots, converted to `16.2.0-beta.1` for NPM)
+
+2. **`dry_run`** (optional): `true` to preview changes without releasing
+
+   - Default: `false`
+
+3. **`registry`** (optional): Publishing registry for testing
+
+   - `verdaccio`: Publish all NPM packages to local Verdaccio (skips RubyGems)
+   - `npm`: Normal release to npmjs.org + rubygems.org (default)
+
+4. **`skip_push`** (optional): Skip git push to remote
+   - `skip_push`: Don't push commits/tags to remote
+   - Default: pushes to remote
+
+**Examples:**
 
 ```bash
-rake release[16.2.0]        # Release version 16.2.0
-rake release[16.2.0,true]   # Dry run to preview changes
-rake release                # Auto-bump patch version
+rake release[patch]                          # Bump patch version (16.1.1 → 16.1.2)
+rake release[minor]                          # Bump minor version (16.1.1 → 16.2.0)
+rake release[major]                          # Bump major version (16.1.1 → 17.0.0)
+rake release[16.2.0]                         # Set explicit version
+rake release[16.2.0.beta.1]                  # Set pre-release version (→ 16.2.0-beta.1 for NPM)
+rake release[16.2.0,true]                    # Dry run to preview changes
+rake release[16.2.0,false,verdaccio]         # Test with local Verdaccio
+rake release[patch,false,npm,skip_push]      # Release but don't push to GitHub
 ```
 
 ### What Gets Released
 
-The release task publishes three packages with the same version number:
+The release task publishes 5 packages with unified versioning:
 
-1. **react-on-rails** NPM package
-2. **react-on-rails-pro** NPM package
-3. **react_on_rails** Ruby gem
+**PUBLIC (npmjs.org + rubygems.org):**
+
+1. **react-on-rails** - NPM package
+2. **react-on-rails-pro** - NPM package
+3. **react_on_rails** - RubyGem
+
+**PRIVATE (GitHub Packages):** 4. **@shakacode-tools/react-on-rails-pro-node-renderer** - NPM package 5. **react_on_rails_pro** - RubyGem
 
 ### Version Synchronization
 
 The task updates versions in all the following files:
 
-- `lib/react_on_rails/version.rb` (source of truth)
+**Core package:**
+
+- `lib/react_on_rails/version.rb` (source of truth for all packages)
 - `package.json` (root workspace)
 - `packages/react-on-rails/package.json`
-- `packages/react-on-rails-pro/package.json` (both version field and react-on-rails dependency)
+- `Gemfile.lock` (root)
 - `spec/dummy/Gemfile.lock`
 
-**Note:** The `react-on-rails-pro` package declares an exact version dependency on `react-on-rails` (e.g., `"react-on-rails": "16.2.0"`). This ensures users install compatible versions of both packages.
+**Pro package:**
+
+- `react_on_rails_pro/lib/react_on_rails_pro/version.rb` (VERSION only, not PROTOCOL_VERSION)
+- `react_on_rails_pro/package.json` (node-renderer)
+- `packages/react-on-rails-pro/package.json` (+ dependency version)
+- `react_on_rails_pro/Gemfile.lock`
+- `react_on_rails_pro/spec/dummy/Gemfile.lock`
+
+**Note:**
+
+- `react_on_rails_pro.gemspec` dynamically references `ReactOnRails::VERSION`
+- `react-on-rails-pro` NPM dependency is pinned to exact version (e.g., `"react-on-rails": "16.2.0"`)
 
 ### Pre-release Versions
 
@@ -107,14 +145,85 @@ After a successful release, you'll see instructions to:
 
 ## Requirements
 
-This task depends on the `gem-release` Ruby gem, which is installed via `bundle install`.
+### NPM Publishing
+
+You must be logged in and have publish permissions:
 
-For NPM publishing, you must be logged in to npm and have publish permissions for both packages:
+**For public packages (npmjs.org):**
 
 ```bash
 npm login
 ```
 
+**For private packages (GitHub Packages):**
+
+- Get a GitHub personal access token with `write:packages` scope
+- Add to `~/.npmrc`:
+  ```ini
+  //npm.pkg.github.com/:_authToken=<TOKEN>
+  always-auth=true
+  ```
+- Set environment variable:
+  ```bash
+  export GITHUB_TOKEN=<TOKEN>
+  ```
+
+### RubyGems Publishing
+
+**For public gem (rubygems.org):**
+
+- Standard RubyGems credentials via `gem push`
+
+**For private gem (GitHub Packages):**
+
+- Add to `~/.gem/credentials`:
+  ```
+  :github: Bearer <GITHUB_TOKEN>
+  ```
+
+### Ruby Version Management
+
+The script automatically detects and switches Ruby versions when needed:
+
+- Supports: RVM, rbenv, asdf
+- Set via `RUBY_VERSION_MANAGER` environment variable (default: `rvm`)
+- Example: Pro dummy app requires Ruby 3.3.7, script auto-switches from 3.3.0
+
+### Dependencies
+
+This task depends on the `gem-release` Ruby gem, which is installed via `bundle install`.
+
+## Testing with Verdaccio
+
+Before releasing to production, test the release process locally:
+
+1. Install and start Verdaccio:
+
+   ```bash
+   npm install -g verdaccio
+   verdaccio
+   ```
+
+2. Run release with verdaccio registry:
+
+   ```bash
+   rake release[patch,false,verdaccio]
+   ```
+
+3. This will:
+
+   - Publish all 3 NPM packages to local Verdaccio
+   - Skip RubyGem publishing
+   - Update version files (revert manually after testing)
+
+4. Test installing from Verdaccio:
+   ```bash
+   npm set registry http://localhost:4873/
+   npm install react-on-rails@16.2.0
+   # Reset when done:
+   npm config delete registry
+   ```
+
 ## Troubleshooting
 
 ### Dry Run First
 
@@ -4,8 +4,17 @@
 
 module ReactOnRails
   class Engine < ::Rails::Engine
+    # Validate package versions and compatibility on Rails startup
+    # This ensures the application fails fast if versions don't match or packages are misconfigured
+    initializer "react_on_rails.validate_version_and_package_compatibility" do
+      config.after_initialize do
+        Rails.logger.info "[React on Rails] Validating package version and compatibility..."
+        VersionChecker.build.validate_version_and_package_compatibility!
+        Rails.logger.info "[React on Rails] Package validation successful"
+      end
+    end
+
     config.to_prepare do
-      VersionChecker.build.log_if_gem_and_node_package_versions_differ
       ReactOnRails::ServerRenderingPool.reset_pool
     end
 
 
@@ -5,6 +5,7 @@
 require "rainbow"
 require "active_support"
 require "active_support/core_ext/string"
+require "shellwords"
 
 # rubocop:disable Metrics/ModuleLength
 module ReactOnRails
@@ -283,6 +284,125 @@ def self.prepend_to_file_if_text_not_present(file:, text_to_prepend:, regex:)
       puts "Prepended\n#{text_to_prepend}to #{file}."
     end
 
+    # Detects which package manager is being used.
+    # First checks the packageManager field in package.json (Node.js Corepack standard),
+    # then falls back to checking for lock files.
+    #
+    # @return [Symbol] The package manager symbol (:npm, :yarn, :pnpm, :bun)
+    def self.detect_package_manager
+      manager = detect_package_manager_from_package_json || detect_package_manager_from_lock_files
+      manager || :yarn # Default to yarn if no detection succeeds
+    end
+
+    # Validates package_name input to prevent command injection
+    #
+    # @param package_name [String] The package name to validate
+    # @raise [ReactOnRails::Error] if package_name contains potentially unsafe characters
+    private_class_method def self.validate_package_name!(package_name)
+      raise ReactOnRails::Error, "package_name cannot be nil" if package_name.nil?
+      raise ReactOnRails::Error, "package_name cannot be empty" if package_name.to_s.strip.empty?
+
+      # Allow valid npm package names: alphanumeric, hyphens, underscores, dots, slashes (for scoped packages)
+      # See: https://github.com/npm/validate-npm-package-name
+      return if package_name.match?(%r{\A[@a-z0-9][a-z0-9._/-]*\z}i)
+
+      raise ReactOnRails::Error, "Invalid package name: #{package_name.inspect}. " \
+                                 "Package names must contain only alphanumeric characters, " \
+                                 "hyphens, underscores, dots, and slashes (for scoped packages)."
+    end
+
+    # Validates package_name and version inputs to prevent command injection
+    #
+    # @param package_name [String] The package name to validate
+    # @param version [String] The version to validate
+    # @raise [ReactOnRails::Error] if inputs contain potentially unsafe characters
+    private_class_method def self.validate_package_command_inputs!(package_name, version)
+      validate_package_name!(package_name)
+
+      raise ReactOnRails::Error, "version cannot be nil" if version.nil?
+      raise ReactOnRails::Error, "version cannot be empty" if version.to_s.strip.empty?
+
+      # Allow valid semver versions and common npm version patterns
+      # This allows: 1.2.3, 1.2.3-beta.1, 1.2.3-alpha, etc.
+      return if version.match?(/\A[a-z0-9][a-z0-9._-]*\z/i)
+
+      raise ReactOnRails::Error, "Invalid version: #{version.inspect}. " \
+                                 "Versions must contain only alphanumeric characters, dots, hyphens, and underscores."
+    end
+
+    private_class_method def self.detect_package_manager_from_package_json
+      package_json_path = File.join(Rails.root, ReactOnRails.configuration.node_modules_location, "package.json")
+      return nil unless File.exist?(package_json_path)
+
+      package_json_data = JSON.parse(File.read(package_json_path))
+      return nil unless package_json_data["packageManager"]
+
+      manager_string = package_json_data["packageManager"]
+      # Extract manager name from strings like "yarn@3.6.0" or "pnpm@8.0.0"
+      manager_name = manager_string.split("@").first
+      manager_name.to_sym if %w[npm yarn pnpm bun].include?(manager_name)
+    rescue StandardError
+      nil
+    end
+
+    private_class_method def self.detect_package_manager_from_lock_files
+      root = Rails.root
+      return :yarn if File.exist?(File.join(root, "yarn.lock"))
+      return :pnpm if File.exist?(File.join(root, "pnpm-lock.yaml"))
+      return :bun if File.exist?(File.join(root, "bun.lockb"))
+      return :npm if File.exist?(File.join(root, "package-lock.json"))
+
+      nil
+    end
+
+    # Returns the appropriate install command for the detected package manager.
+    # Generates the correct command with exact version syntax.
+    #
+    # @param package_name [String] The name of the package to install
+    # @param version [String] The exact version to install
+    # @return [String] The command to run (e.g., "yarn add react-on-rails@16.0.0 --exact")
+    def self.package_manager_install_exact_command(package_name, version)
+      validate_package_command_inputs!(package_name, version)
+
+      manager = detect_package_manager
+      # Escape shell arguments to prevent command injection
+      safe_package = Shellwords.escape("#{package_name}@#{version}")
+
+      case manager
+      when :pnpm
+        "pnpm add #{safe_package} --save-exact"
+      when :bun
+        "bun add #{safe_package} --exact"
+      when :npm
+        "npm install #{safe_package} --save-exact"
+      else # :yarn or unknown, default to yarn
+        "yarn add #{safe_package} --exact"
+      end
+    end
+
+    # Returns the appropriate remove command for the detected package manager.
+    #
+    # @param package_name [String] The name of the package to remove
+    # @return [String] The command to run (e.g., "yarn remove react-on-rails")
+    def self.package_manager_remove_command(package_name)
+      validate_package_name!(package_name)
+
+      manager = detect_package_manager
+      # Escape shell arguments to prevent command injection
+      safe_package = Shellwords.escape(package_name)
+
+      case manager
+      when :pnpm
+        "pnpm remove #{safe_package}"
+      when :bun
+        "bun remove #{safe_package}"
+      when :npm
+        "npm uninstall #{safe_package}"
+      else # :yarn or unknown, default to yarn
+        "yarn remove #{safe_package}"
+      end
+    end
+
     def self.default_troubleshooting_section
       <<~DEFAULT
         📞 Get Help & Support: