Unify release scripts and add strict version validation

docs/contributor-info/releasing.md

@@ -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

lib/react_on_rails/engine.rb

@@ -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
 

lib/react_on_rails/utils.rb

@@ -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: