Merge remote-tracking branch 'origin/main' into codex/pr-3142-work

* origin/main:
  docs: amend CHANGELOG entry for #3229 scope drift
  fix: validate selected JavaScript package manager
  fix: preserve causes when wrapping render errors (#3230)

# Conflicts:
#	CHANGELOG.md

Author: justin808

CHANGELOG.md

@@ -40,6 +40,8 @@ After a release, run `/update-changelog` in Claude Code to analyze commits, writ
 
 #### Fixed
 
+- **Install generator validates the selected JavaScript package manager**: The install generator now checks the manager selected from `REACT_ON_RAILS_PACKAGE_MANAGER`, the `packageManager` field in `package.json`, or a lockfile on disk — instead of passing when any JavaScript package manager is installed. When the selected command is missing, the error names the selected manager, the source that selected it, and the available alternatives. The generator also warns when `REACT_ON_RAILS_PACKAGE_MANAGER` is set to a value outside the supported set (`npm`, `pnpm`, `yarn`, `bun`). Addresses package manager validation from [Issue 1958](https://github.com/shakacode/react_on_rails/issues/1958). [PR 3229](https://github.com/shakacode/react_on_rails/pull/3229) by [justin808](https://github.com/justin808).
+- **Server-render error wrapping preserves original causes**: When server rendering catches a non-`Error` thrown value, React on Rails now wraps it with the original value attached as `cause`, making downstream debugging preserve more context. Fixes [Issue 1746](https://github.com/shakacode/react_on_rails/issues/1746). [PR 3230](https://github.com/shakacode/react_on_rails/pull/3230) by [justin808](https://github.com/justin808).
 - **`bin/dev` now cleans copied runtime files before startup**: When you duplicate an app directory to run another local dev stack, `bin/dev` now removes copied stale Overmind sockets and stale `tmp/pids/server.pid` files that point to a Puma process running from another app directory. This prevents false startup failures in copied workspaces while still preserving active local sockets and pid files for the current app. [PR 3142](https://github.com/shakacode/react_on_rails/pull/3142) by [justin808](https://github.com/justin808).
 - **[Pro]** **Node renderer now exposes `performance` when `supportModules: true`**: React 19's development build of `React.lazy` calls `performance.now()`, which previously threw `ReferenceError: performance is not defined` inside the node renderer's VM context unless users manually added `performance` via `additionalContext`. `performance` is now included in the default globals alongside `Buffer`, `process`, etc. Fixes [Issue 3154](https://github.com/shakacode/react_on_rails/issues/3154). [PR 3158](https://github.com/shakacode/react_on_rails/pull/3158) by [justin808](https://github.com/justin808).
 - **Client startup now recovers if initialization begins during `interactive` after `DOMContentLoaded` already fired**: React on Rails now still initializes the page when the client bundle starts in the browser timing window after `DOMContentLoaded` but before the document reaches `complete`. Fixes [Issue 3150](https://github.com/shakacode/react_on_rails/issues/3150). [PR 3151](https://github.com/shakacode/react_on_rails/pull/3151) by [ihabadham](https://github.com/ihabadham).

packages/react-on-rails-pro-node-renderer/tests/serverRenderRSCReactComponent.test.js

@@ -142,7 +142,9 @@ describe('serverRenderRSCReactComponent', () => {
 
     if (expectedError) {
       expect(onError).toHaveBeenCalled();
-      expect(onError).toHaveBeenCalledWith(new Error(expectedError));
+      const [emittedError] = onError.mock.calls[0];
+      expect(Object.prototype.toString.call(emittedError)).toBe('[object Error]');
+      expect(emittedError.message).toBe(expectedError);
     }
 
     expectedContents.forEach((text) => {

packages/react-on-rails/src/serverRenderUtils.ts

@@ -24,8 +24,37 @@ export function createResultObject(
   };
 }
 
+function isCrossRealmError(e: unknown): e is { message?: unknown } {
+  return typeof e === 'object' && e !== null && Object.prototype.toString.call(e) === '[object Error]';
+}
+
+function stringifyThrownValue(e: unknown): string {
+  if (isCrossRealmError(e)) {
+    return typeof e.message === 'string' ? e.message : Object.prototype.toString.call(e);
+  }
+
+  if (typeof e === 'object' && e !== null) {
+    try {
+      // JSON.stringify can return undefined without throwing, for example when toJSON returns undefined.
+      return JSON.stringify(e) ?? Object.prototype.toString.call(e);
+    } catch {
+      return Object.prototype.toString.call(e);
+    }
+  }
+
+  return String(e);
+}
+
 export function convertToError(e: unknown): Error {
-  return e instanceof Error ? e : new Error(String(e));
+  if (e instanceof Error) {
+    return e;
+  }
+
+  const message = stringifyThrownValue(e);
+  // tsconfig uses es2020 libs, which do not type Error.cause even though supported runtimes provide it.
+  const error = new Error(message) as Error & { cause?: unknown };
+  error.cause = e;
+  return error;
 }
 
 export function validateComponent(componentObj: RegisteredComponent, componentName: string) {

packages/react-on-rails/tests/serverRenderUtils.test.ts

@@ -0,0 +1,90 @@
+import { Script } from 'node:vm';
+
+import { convertToError } from '../src/serverRenderUtils.ts';
+
+type ErrorWithCause = Error & { cause?: unknown };
+
+describe('serverRenderUtils', () => {
+  describe('convertToError', () => {
+    it('returns Error instances unchanged', () => {
+      const error = new Error('Already an error');
+
+      expect(convertToError(error)).toBe(error);
+    });
+
+    it('wraps plain object thrown values with a readable message while preserving the original cause', () => {
+      const thrownValue = { message: 'plain object failure' };
+
+      const error = convertToError(thrownValue);
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error.message).toBe('{"message":"plain object failure"}');
+      expect((error as ErrorWithCause).cause).toBe(thrownValue);
+    });
+
+    it('wraps a thrown string with the string as the message and cause', () => {
+      const error = convertToError('something went wrong');
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error.message).toBe('something went wrong');
+      expect((error as ErrorWithCause).cause).toBe('something went wrong');
+    });
+
+    it('wraps a thrown number', () => {
+      const error = convertToError(42);
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error.message).toBe('42');
+      expect((error as ErrorWithCause).cause).toBe(42);
+    });
+
+    it('wraps null thrown values', () => {
+      const error = convertToError(null);
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error.message).toBe('null');
+      expect((error as ErrorWithCause).cause).toBeNull();
+    });
+
+    it('wraps undefined thrown values', () => {
+      const error = convertToError(undefined);
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error.message).toBe('undefined');
+      expect((error as ErrorWithCause).cause).toBeUndefined();
+    });
+
+    it('wraps circular-reference objects without throwing', () => {
+      const circular: Record<string, unknown> = {};
+      circular.self = circular;
+
+      const error = convertToError(circular);
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error.message).toBe('[object Object]');
+      expect((error as ErrorWithCause).cause).toBe(circular);
+    });
+
+    it('wraps errors thrown from another JavaScript realm with their original message', () => {
+      const thrownValue: unknown = new Script('new Error("cross-realm failure")').runInNewContext();
+
+      const error = convertToError(thrownValue);
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error.message).toBe('cross-realm failure');
+      expect((error as ErrorWithCause).cause).toBe(thrownValue);
+    });
+
+    it('wraps cross-realm errors with non-string messages using the error tag', () => {
+      const thrownValue: unknown = new Script(
+        'const error = new Error(); error.message = 42; error',
+      ).runInNewContext();
+
+      const error = convertToError(thrownValue);
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error.message).toBe('[object Error]');
+      expect((error as ErrorWithCause).cause).toBe(thrownValue);
+    });
+  });
+});

react_on_rails/lib/generators/react_on_rails/generator_messages/package_manager_detection.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "react_on_rails/utils"
 
 module GeneratorMessages
   # Package-manager detection helpers used by the install generator and the
@@ -9,6 +10,15 @@ module GeneratorMessages
   module PackageManagerDetection
     SUPPORTED_PACKAGE_MANAGERS = %w[npm pnpm yarn bun].freeze
 
+    # Hash insertion order is the detection priority used by
+    # detect_package_manager_from_lockfiles (yarn → pnpm → bun → npm).
+    LOCKFILE_CANDIDATES_BY_MANAGER = {
+      "yarn" => ["yarn.lock"],
+      "pnpm" => ["pnpm-lock.yaml"],
+      "bun" => ["bun.lock", "bun.lockb"],
+      "npm" => ["package-lock.json"]
+    }.freeze
+
     # Detects the package manager in priority order:
     # 1. REACT_ON_RAILS_PACKAGE_MANAGER env variable
     # 2. packageManager field in package.json (Corepack standard)
@@ -20,15 +30,26 @@ module PackageManagerDetection
     # Pass package_json: to reuse an already-parsed package.json and avoid a re-read
     # (callers that also inspect scripts/deps should parse once and pass the hash).
     def detect_package_manager(app_root: Dir.pwd, package_json: nil)
+      detect_package_manager_with_source(app_root: app_root, package_json: package_json).first
+    end
+
+    # source is one of :env, :package_json, :lockfile, :default — used to
+    # name the originating source when surfacing detection errors.
+    def detect_package_manager_with_source(app_root: Dir.pwd, package_json: nil)
       env_package_manager = ENV.fetch("REACT_ON_RAILS_PACKAGE_MANAGER", nil)&.strip&.downcase
-      return env_package_manager if supported_package_manager?(env_package_manager)
+      return [env_package_manager, :env] if supported_package_manager?(env_package_manager)
 
       pm_from_json = if package_json
                        package_manager_from_content(package_json)
                      else
                        detect_package_manager_from_package_json(app_root: app_root)
                      end
-      pm_from_json || detect_package_manager_from_lockfiles(app_root: app_root) || "npm"
+      return [pm_from_json, :package_json] if pm_from_json
+
+      pm_from_lockfile = detect_package_manager_from_lockfiles(app_root: app_root)
+      return [pm_from_lockfile, :lockfile] if pm_from_lockfile
+
+      ["npm", :default]
     end
 
     def package_manager_from_content(content)
@@ -39,35 +60,35 @@ def package_manager_from_content(content)
       supported_package_manager?(name) ? name : nil
     end
 
-    def detect_package_manager_from_lockfiles(app_root: Dir.pwd)
-      return "yarn" if File.exist?(File.join(app_root, "yarn.lock"))
-      return "pnpm" if File.exist?(File.join(app_root, "pnpm-lock.yaml"))
-      return "bun" if File.exist?(File.join(app_root, "bun.lock")) || File.exist?(File.join(app_root, "bun.lockb"))
-      return "npm" if File.exist?(File.join(app_root, "package-lock.json"))
-
-      nil
+    def lockfile_filename_for(package_manager, app_root: Dir.pwd)
+      LOCKFILE_CANDIDATES_BY_MANAGER[package_manager]&.find do |name|
+        File.exist?(File.join(app_root, name))
+      end
     end
 
-    # Returns true only when a lockfile for the specific package manager exists.
-    # Used by the CI scaffold so `cache:` / `<pm> install` never reference a
-    # lockfile that is not actually on disk (e.g. `packageManager: pnpm` without
-    # `pnpm-lock.yaml`, which breaks `actions/setup-node`'s cache step).
+    # Used by the CI scaffold so `cache:` / `<pm> install` never reference a lockfile
+    # that's not on disk (e.g. `packageManager: pnpm` without `pnpm-lock.yaml`, which
+    # breaks `actions/setup-node`'s cache step).
     def lockfile_for_manager?(package_manager, app_root: Dir.pwd)
-      case package_manager
-      when "yarn" then File.exist?(File.join(app_root, "yarn.lock"))
-      when "pnpm" then File.exist?(File.join(app_root, "pnpm-lock.yaml"))
-      when "bun"
-        File.exist?(File.join(app_root, "bun.lock")) ||
-          File.exist?(File.join(app_root, "bun.lockb"))
-      when "npm" then File.exist?(File.join(app_root, "package-lock.json"))
-      else false
+      !lockfile_filename_for(package_manager, app_root: app_root).nil?
+    end
+
+    def detect_package_manager_from_lockfiles(app_root: Dir.pwd)
+      LOCKFILE_CANDIDATES_BY_MANAGER.keys.find do |pm|
+        lockfile_for_manager?(pm, app_root: app_root)
       end
     end
 
     def supported_package_manager?(package_manager)
       SUPPORTED_PACKAGE_MANAGERS.include?(package_manager)
     end
 
+    def package_manager_executable_available?(package_manager)
+      return false unless supported_package_manager?(package_manager)
+
+      ReactOnRails::Utils.command_available?(package_manager)
+    end
+
     private
 
     # Pipeline internals — external callers should go through `detect_package_manager`

react_on_rails/lib/generators/react_on_rails/install_generator.rb

@@ -417,6 +417,8 @@ def ensure_jsx_in_js_compatibility
       # js(.coffee) are not checked by this method, but instead produce warning messages
       # and allow the build to continue
       def installation_prerequisites_met?
+        warn_if_unsupported_env_package_manager
+
         # Non-blocking: warn about dirty worktree but don't prevent installation.
         # A clean tree makes the generator diff easier to review, but blocking would
         # be too strict for a generator that creates many new files.
@@ -442,10 +444,21 @@ def installation_prerequisites_met?
         !(missing_node? || missing_package_manager? || (!has_worktree_issues && missing_pro_gem?))
       end
 
-      def missing_node?
-        node_missing = ReactOnRails::Utils.running_on_windows? ? `where node`.blank? : `which node`.blank?
+      def warn_if_unsupported_env_package_manager
+        env_value = ENV.fetch("REACT_ON_RAILS_PACKAGE_MANAGER", nil)&.strip
+        return if env_value.nil? || env_value.empty?
+        return if GeneratorMessages.supported_package_manager?(env_value.downcase)
+
+        supported = GeneratorMessages::SUPPORTED_PACKAGE_MANAGERS.join(", ")
+        GeneratorMessages.add_warning(<<~MSG.strip)
+          ⚠️  REACT_ON_RAILS_PACKAGE_MANAGER='#{env_value}' is not a supported package manager.
+          Supported values: #{supported}.
+          Falling through to package.json / lockfile / npm-default detection.
+        MSG
+      end
 
-        if node_missing
+      def missing_node?
+        unless ReactOnRails::Utils.command_available?("node")
           error = <<~MSG.strip
             🚫 Node.js is required but not found on your system.
 
@@ -734,8 +747,7 @@ def shakapacker_in_gemfile_text?(gem_name)
       end
 
       def cli_exists?(command)
-        which_command = ReactOnRails::Utils.running_on_windows? ? "where" : "which"
-        system(which_command, command, out: File::NULL, err: File::NULL)
+        ReactOnRails::Utils.command_available?(command)
       end
 
       def normalize_bin_dev_content(content)
@@ -946,13 +958,19 @@ def handle_shakapacker_install_error
       end
 
       def missing_package_manager?
-        package_managers = %w[npm pnpm yarn bun]
-        missing = package_managers.none? { |pm| cli_exists?(pm) }
+        selected, source = GeneratorMessages.detect_package_manager_with_source(app_root: destination_root)
+        return false if GeneratorMessages.package_manager_executable_available?(selected)
 
-        if missing
+        available_package_managers = GeneratorMessages::SUPPORTED_PACKAGE_MANAGERS.select do |pm|
+          pm != selected && GeneratorMessages.package_manager_executable_available?(pm)
+        end
+
+        if available_package_managers.empty?
           error = <<~MSG.strip
             🚫 No JavaScript package manager found on your system.
 
+            #{package_manager_source_description(selected, source)}
+
             React on Rails requires a JavaScript package manager to install dependencies.
             Please install one of the following:
 
@@ -967,7 +985,32 @@ def missing_package_manager?
           return true
         end
 
-        false
+        action_separator = %i[default env].include?(source) ? " or " : ", update the source above, or "
+        error = <<~MSG.strip
+          🚫 JavaScript package manager '#{selected}' was selected, but the command was not found.
+
+          #{package_manager_source_description(selected, source)}
+          Install '#{selected}'#{action_separator}set REACT_ON_RAILS_PACKAGE_MANAGER
+          to one of the available package managers: #{available_package_managers.join(', ')}.
+        MSG
+        GeneratorMessages.add_error(error)
+        true
+      end
+
+      def package_manager_source_description(selected, source)
+        case source
+        when :env
+          "Selected via the REACT_ON_RAILS_PACKAGE_MANAGER environment variable."
+        when :package_json
+          "Selected via the `packageManager` field in package.json."
+        when :lockfile
+          lockfile = GeneratorMessages.lockfile_filename_for(selected, app_root: destination_root)
+          lockfile ? "Selected via the #{lockfile} lockfile on disk." : "Selected via a lockfile on disk."
+        when :default
+          "Selected via the npm default fallback (no env var, packageManager field, or lockfile detected)."
+        else
+          raise ArgumentError, "Unknown package manager source: #{source.inspect}"
+        end
       end
 
       def jsx_in_js_files_present?

react_on_rails/lib/react_on_rails/utils.rb

@@ -161,6 +161,11 @@ def self.running_on_windows?
       (/cygwin|mswin|mingw|bccwin|wince|emx/ =~ RUBY_PLATFORM) != nil
     end
 
+    def self.command_available?(command)
+      which_command = running_on_windows? ? "where" : "which"
+      !!system(which_command, command, out: File::NULL, err: File::NULL)
+    end
+
     def self.rails_version_less_than(version)
       @rails_version_less_than ||= {}