fix: address PR B review feedback for unified renderer cache staging

- Doctor check now tailors the suggested migration command per matched
  file type: Dockerfile entries get the bare 'rake pre_seed_renderer_cache'
  (MODE=copy is the default); Procfile/bin entries get 'MODE=symlink'.
- The copy-mode env-var error now mentions 'MODE=symlink' as an escape
  hatch for CI users who don't need an immutable artifact.
- make_relative_symlink rescues Errno::ENOENT from Pathname#realpath and
  surfaces a clearer ReactOnRailsPro::Error when a bundle/asset vanished
  between existence check and staging (e.g. webpack output rotating
  mid-stage, dangling symlinks in the source tree).
- PrepareNodeRenderBundles.reset_deprecation_warned! is now
  private_class_method; specs invoke it via send.
- Rake task now downcases ENV['MODE'] and validates against
  PreSeedRendererCache::VALID_MODES before to_sym, accepting 'MODE=Copy',
  'MODE=COPY', etc. Unknown values abort with a clear error listing
  valid modes.
- Added a :symlink-mode spec that exercises asset symlinking (previously
  only covered via the PrepareNodeRenderBundles shim).
- env-var-bypass spec now uses ensure block with a local tmpdir variable
  to guarantee cleanup even if Dir.mktmpdir or an intermediate assertion
  raises.

Declined: thread-safety wrapper around @deprecation_warned. This code
runs only from rake tasks and AssetsPrecompile.call (single-threaded
contexts); a race would produce at most a harmless duplicate warning,
not a correctness issue. Consistent with PR A precedent for
@renderer_bundle_path_deprecation_warned.

27 dummy specs pass; rubocop clean on all changed files.

Refs: #3122, #3167

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: justin808

react_on_rails/lib/react_on_rails/doctor.rb

@@ -2748,10 +2748,7 @@ def check_deprecated_renderer_cache_task
 
       checker.add_warning(<<~MSG.strip)
         ⚠️  Deprecated rake task '#{DEPRECATED_RENDERER_CACHE_TASK}' referenced in:
-        #{matches.map { |p| "  • #{p}" }.join("\n")}
-
-        Replace with:
-          rake react_on_rails_pro:pre_seed_renderer_cache MODE=symlink
+        #{matches.map { |p| "  • #{p} → #{renderer_cache_migration_suggestion(p)}" }.join("\n")}
 
         The unified 'pre_seed_renderer_cache' task uses MODE=copy by default (for
         Docker/image builds) and MODE=symlink for same-filesystem workflows.
@@ -2760,6 +2757,17 @@ def check_deprecated_renderer_cache_task
       checker.add_warning("⚠️  Could not scan for deprecated renderer-cache task references: #{e.message}")
     end
 
+    # Dockerfile matches mean the user is building an image, so they want the
+    # copy-mode default (no MODE needed). Procfile/bin scripts mean same-filesystem
+    # runtime staging, which needs the symlink mode.
+    def renderer_cache_migration_suggestion(path)
+      if path.start_with?("Dockerfile")
+        "rake react_on_rails_pro:pre_seed_renderer_cache"
+      else
+        "rake react_on_rails_pro:pre_seed_renderer_cache MODE=symlink"
+      end
+    end
+
     # The base 'react-on-rails' npm package is a transitive dependency of 'react-on-rails-pro',
     # so `import ... from 'react-on-rails'` resolves silently — loading the base package instead
     # of Pro. Components registered through the base package won't have Pro features (streaming,

react_on_rails_pro/lib/react_on_rails_pro/pre_seed_renderer_cache.rb

@@ -69,6 +69,11 @@ def self.enforce_cache_dir_env_var!(mode)
         The Node Renderer's default cache directory resolution differs between the Ruby
         and standalone Node environments, so relying on the default in production-like
         deploys can cause pre-seeded bundles to land in a path the renderer never reads.
+
+        If you don't need an immutable artifact (e.g. in CI or same-filesystem deploys),
+        use mode: :symlink instead:
+
+          rake react_on_rails_pro:pre_seed_renderer_cache MODE=symlink
       MSG
     end
     private_class_method :enforce_cache_dir_env_var!
@@ -127,10 +132,19 @@ def self.make_relative_symlink(source, destination)
 
       # Canonicalize both sides so paths like /var -> /private/var do not
       # produce broken relative symlinks when the cache dir comes from tmpdir.
+      # Pathname#realpath raises Errno::ENOENT on a dangling symlink or a
+      # path that vanished between File.exist? and here (e.g. webpack output
+      # rotating mid-stage). Surface that as a clear ReactOnRailsPro::Error
+      # rather than a raw system error.
       source_path = Pathname.new(source).realpath
       relative_source_path = source_path.relative_path_from(destination_dir.realpath)
       File.symlink(relative_source_path, destination)
       puts "[ReactOnRailsPro] Symlinked #{relative_source_path} to #{destination}"
+    rescue Errno::ENOENT => e
+      raise ReactOnRailsPro::Error,
+            "Could not resolve real path for symlink source #{source} " \
+            "(#{e.message}). The file may have been removed or may be a dangling symlink. " \
+            "Rebuild your bundles before staging the renderer cache."
     end
     private_class_method :make_relative_symlink
   end

react_on_rails_pro/lib/react_on_rails_pro/prepare_node_renderer_bundles.rb

@@ -25,8 +25,11 @@ def self.emit_deprecation_warning!
 
     # :nodoc: Test helper — resets the one-time deprecation-warning guard so
     # specs can exercise the warning path without leaking state between examples.
+    # Private so it can only be invoked from specs via `send`; prevents accidental
+    # reset from production code.
     def self.reset_deprecation_warned!
       @deprecation_warned = nil
     end
+    private_class_method :reset_deprecation_warned!
   end
 end

react_on_rails_pro/lib/tasks/assets.rake

@@ -6,8 +6,13 @@ namespace :react_on_rails_pro do
   desc "Stage the Node Renderer bundle cache. MODE=copy (default; Docker/image builds) " \
        "or MODE=symlink (dev/CI/same-filesystem deploys)."
   task pre_seed_renderer_cache: :environment do
-    mode = (ENV["MODE"] || "copy").to_sym
-    ReactOnRailsPro::PreSeedRendererCache.call(mode: mode)
+    raw_mode = ENV["MODE"].to_s.downcase
+    raw_mode = "copy" if raw_mode.empty?
+    unless ReactOnRailsPro::PreSeedRendererCache::VALID_MODES.map(&:to_s).include?(raw_mode)
+      valid = ReactOnRailsPro::PreSeedRendererCache::VALID_MODES.map(&:to_s).join(", ")
+      abort "[ReactOnRailsPro] Unknown MODE=#{ENV.fetch('MODE', nil).inspect}. Expected one of: #{valid}"
+    end
+    ReactOnRailsPro::PreSeedRendererCache.call(mode: raw_mode.to_sym)
   end
 
   # Deprecated alias. Delegates to pre_seed_renderer_cache with MODE=symlink so

react_on_rails_pro/spec/dummy/spec/pre_seed_renderer_cache_spec.rb

@@ -60,13 +60,26 @@
   end
 
   context "when mode is :symlink" do
-    it "symlinks instead of copying" do
+    it "symlinks the bundle instead of copying it" do
       described_class.call(mode: :symlink)
 
       dest_file = File.join(bundle_dir, "#{bundle_hash}.js")
       expect(File.exist?(dest_file)).to be(true)
       expect(File.symlink?(dest_file)).to be(true)
     end
+
+    it "symlinks assets rather than copying them" do
+      FileUtils.cp(fixture_path, path_in_webpack_folder(asset_filename))
+      FileUtils.cp(fixture_path2, path_in_webpack_folder(asset_filename2))
+
+      described_class.call(mode: :symlink)
+
+      first_asset = File.join(bundle_dir, asset_filename)
+      second_asset = File.join(bundle_dir, asset_filename2)
+      expect(File.symlink?(first_asset)).to be(true)
+      expect(File.symlink?(second_asset)).to be(true)
+      expect(File.realpath(first_asset)).to eq(path_in_webpack_folder(asset_filename).to_s)
+    end
   end
 
   context "when mode is :copy and no env var is set in a non-dev/test environment" do
@@ -81,10 +94,12 @@
     end
 
     it "does not raise when the preferred env var is set" do
-      ENV["RENDERER_SERVER_BUNDLE_CACHE_PATH"] = Dir.mktmpdir("renderer-cache-test")
+      tmpdir = Dir.mktmpdir("renderer-cache-test")
+      ENV["RENDERER_SERVER_BUNDLE_CACHE_PATH"] = tmpdir
       expect { described_class.call(mode: :copy) }.not_to raise_error
     ensure
-      FileUtils.rm_rf(ENV.fetch("RENDERER_SERVER_BUNDLE_CACHE_PATH", nil))
+      FileUtils.rm_rf(tmpdir) if tmpdir
+      ENV.delete("RENDERER_SERVER_BUNDLE_CACHE_PATH")
     end
 
     it "does not raise in :symlink mode even without an env var" do

react_on_rails_pro/spec/dummy/spec/prepare_node_renderer_bundles_spec.rb

@@ -39,7 +39,7 @@
     ENV.delete("RENDERER_SERVER_BUNDLE_CACHE_PATH")
     ENV.delete("RENDERER_BUNDLE_PATH")
     ReactOnRailsPro::Utils.reset_renderer_bundle_path_deprecation_warned!
-    described_class.reset_deprecation_warned!
+    described_class.send(:reset_deprecation_warned!)
   end
 
   after do
@@ -49,7 +49,7 @@
     FileUtils.rm_f(path_in_webpack_folder(asset_filename2))
     ENV.delete("RENDERER_SERVER_BUNDLE_CACHE_PATH")
     ENV.delete("RENDERER_BUNDLE_PATH")
-    described_class.reset_deprecation_warned!
+    described_class.send(:reset_deprecation_warned!)
   end
 
   it "emits a deprecation warning pointing at PreSeedRendererCache" do