shakacode
diff --git a/‎CHANGELOG.md‎
Lines changed: 9 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 9 additions & 0 deletions
diff --git a/‎react_on_rails/lib/generators/react_on_rails/rsc_generator.rb‎
Lines changed: 17 additions & 0 deletions b/‎react_on_rails/lib/generators/react_on_rails/rsc_generator.rb‎
Lines changed: 17 additions & 0 deletions
diff --git a/‎react_on_rails/lib/react_on_rails/agent_guardrails.rb‎
Lines changed: 223 additions & 0 deletions b/‎react_on_rails/lib/react_on_rails/agent_guardrails.rb‎
Lines changed: 223 additions & 0 deletions
@@ -213,6 +213,15 @@ After a release, run `/update-changelog` in Claude Code to analyze commits, writ
 
 #### Added
 
+- **[Pro]** **RSC agent guardrails installer**: New
+  `rake react_on_rails:install_rsc_agent_guardrails` task (also run automatically by the RSC
+  generator) installs a Claude Code `rsc-app-safety` skill and an advisory hook into a host app's
+  `.claude/`, steering AI coding agents away from React Server Components API footguns (mounting the
+  RSC payload route without authentication, trusting server-component props, exposing the Node
+  renderer, leaking secrets). Idempotent and safe to re-run after upgrades.
+  [PR 4606](https://github.com/shakacode/react_on_rails/pull/4606) by
+  [justin808](https://github.com/justin808).
+
 - **[Pro] React 18 support for non-RSC streaming SSR**: `stream_react_component` with synchronous
   props is now explicitly supported on React 18 as well as React 19. Permanent packed-artifact
   coverage verifies a production Webpack build and progressive Suspense output on React 18 without
 
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "rails/generators"
+require "react_on_rails/agent_guardrails"
 require_relative "generator_helper"
 require_relative "generator_messages"
 require_relative "js_dependency_manager"
@@ -53,6 +54,7 @@ def run_generator
           warn_about_react_version_for_rsc(force: true)
           setup_rsc
           add_rsc_npm_dependencies
+          install_agent_guardrails
           print_success_message unless options[:invoked_by_install]
         else
           GeneratorMessages.add_error(<<~MSG.strip)
@@ -120,6 +122,21 @@ def add_rsc_npm_dependencies
         say "✅ RSC npm dependencies added", :green
       end
 
+      def install_agent_guardrails
+        if options[:pretend]
+          say_status :pretend, ".claude/ (RSC agent guardrails)", :yellow
+          return
+        end
+
+        say "🛡️  Installing RSC agent guardrails (rsc-app-safety skill + advisory hook)...", :yellow
+        ReactOnRails::AgentGuardrails.install(destination_root, skip_existing: options[:skip]).each do |action|
+          say "   #{action}"
+        end
+        say "✅ RSC agent guardrails installed", :green
+      rescue ReactOnRails::AgentGuardrails::Error, SystemCallError => e
+        say "⚠️  RSC agent guardrail installation incomplete: #{e.message}", :yellow
+      end
+
       def print_success_message
         GeneratorMessages.add_info(<<~MSG)
           Next steps:
 
@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "tempfile"
+
+module ReactOnRails
+  # Installs (and idempotently updates) the RSC "agent guardrail" assets into a host app:
+  # a Claude Code skill and an advisory PostToolUse hook that steer AI agents away from the
+  # React Server Components API footguns (unauthenticated payload route, trusting props, exposing
+  # the Node renderer, leaking secrets). Invoked by `rake react_on_rails:install_rsc_agent_guardrails`
+  # and by the RSC generator.
+  module AgentGuardrails
+    Error = Class.new(StandardError)
+
+    TEMPLATES_DIR = File.expand_path("agent_guardrails/templates", __dir__)
+
+    # source template (under TEMPLATES_DIR) => destination path relative to the app root
+    FILES = {
+      "rsc_app_safety_skill.md" => ".claude/skills/rsc-app-safety/SKILL.md",
+      "rsc_app_safety_check.rb" => ".claude/hooks/rsc-app-safety-check.rb"
+    }.freeze
+
+    HOOK_COMMAND = "ruby"
+    HOOK_ARGS = ["${CLAUDE_PROJECT_DIR}/.claude/hooks/rsc-app-safety-check.rb"].freeze
+    LEGACY_HOOK_COMMAND = "${CLAUDE_PROJECT_DIR}/.claude/hooks/rsc-app-safety-check.sh"
+    LEGACY_HOOK_REL = ".claude/hooks/rsc-app-safety-check.sh"
+    HOOK_REL = ".claude/hooks/rsc-app-safety-check.rb"
+    HOOK_MATCHER = "Edit|Write"
+    SETTINGS_REL = ".claude/settings.json"
+
+    # Copies the guardrail files and registers the advisory hook. Idempotent: re-running only
+    # writes what changed. Returns an array of human-readable action strings.
+    def self.install(destination_root, skip_existing: false)
+      new_installer(destination_root, skip_existing:).install
+    end
+
+    def self.new_installer(destination_root, skip_existing: false)
+      Installer.new(destination_root, skip_existing:)
+    end
+
+    # Where guardrails get installed when no explicit destination is given. Prefers the Rails
+    # application root so the task installs into the app's `.claude/` even when rake is invoked
+    # from a subdirectory; falls back to the working directory outside a Rails app.
+    def self.default_destination_root(explicit = nil)
+      explicit = explicit.to_s
+      return explicit unless explicit.empty?
+
+      rails_root = defined?(Rails) && Rails.respond_to?(:root) ? Rails.root : nil
+      rails_root ? rails_root.to_s : Dir.pwd
+    end
+
+    # Encapsulates a single install run against one app root.
+    class Installer
+      def initialize(destination_root, skip_existing: false)
+        @destination_root = File.expand_path(destination_root.to_s)
+        @skip_existing = skip_existing
+      end
+
+      def install
+        validate_settings_before_copy
+        actions = FILES.map { |source, dest_rel| copy_file(source, dest_rel) }
+        actions << register_hook
+        actions << remove_legacy_hook
+        actions.compact
+      end
+
+      private
+
+      attr_reader :destination_root, :skip_existing
+
+      def validate_settings_before_copy
+        settings_path = File.join(destination_root, SETTINGS_REL)
+        return if skip_existing && File.exist?(settings_path)
+
+        read_settings(settings_path)
+      end
+
+      def copy_file(source, dest_rel)
+        source_path = File.join(TEMPLATES_DIR, source)
+        dest_path = File.join(destination_root, dest_rel)
+        existed = File.exist?(dest_path)
+        return "skipped    #{dest_rel} (already exists)" if skip_existing && existed
+
+        new_content = File.read(source_path)
+        unchanged = existed && File.read(dest_path) == new_content
+
+        unless unchanged
+          FileUtils.mkdir_p(File.dirname(dest_path))
+          File.write(dest_path, new_content)
+        end
+        File.chmod(0o755, dest_path) if dest_rel == HOOK_REL
+
+        return "unchanged  #{dest_rel}" if unchanged
+
+        existed ? "updated    #{dest_rel}" : "created    #{dest_rel}"
+      end
+
+      def register_hook
+        settings_path = File.join(destination_root, SETTINGS_REL)
+        return "skipped    #{SETTINGS_REL} (already exists)" if skip_existing && File.exist?(settings_path)
+
+        settings = read_settings(settings_path)
+        return "unchanged  #{SETTINGS_REL} (hook already registered)" if hook_registered?(settings)
+
+        add_hook(settings)
+        FileUtils.mkdir_p(File.dirname(settings_path))
+        existed = File.exist?(settings_path)
+        atomic_write(settings_path, "#{JSON.pretty_generate(settings)}\n")
+        existed ? "updated    #{SETTINGS_REL} (registered hook)" : "created    #{SETTINGS_REL} (registered hook)"
+      end
+
+      # settings.json is the user's file and may hold unrelated configuration, so it is replaced by
+      # rename rather than truncate-and-write: an interrupted or failed write can never leave a
+      # half-written or empty settings file behind.
+      def atomic_write(path, content)
+        directory = File.dirname(path)
+        mode = File.exist?(path) ? File.stat(path).mode & 0o7777 : 0o644
+        temp = Tempfile.create([".#{File.basename(path)}", ".tmp"], directory)
+        begin
+          temp.write(content)
+          temp.flush
+          temp.fsync
+          temp.close
+          File.chmod(mode, temp.path)
+          File.rename(temp.path, path)
+        rescue StandardError
+          FileUtils.rm_f(temp.path)
+          raise
+        end
+      end
+
+      def remove_legacy_hook
+        legacy_path = File.join(destination_root, LEGACY_HOOK_REL)
+        return unless File.exist?(legacy_path)
+        return "skipped    #{LEGACY_HOOK_REL} (already exists)" if skip_existing
+
+        FileUtils.rm_f(legacy_path)
+        "removed    #{LEGACY_HOOK_REL} (replaced by #{HOOK_REL})"
+      end
+
+      def read_settings(path)
+        return {} unless File.exist?(path)
+
+        content = File.read(path).strip
+        return {} if content.empty?
+
+        settings = JSON.parse(content)
+        raise Error, invalid_settings_message unless valid_settings_shape?(settings)
+
+        settings
+      rescue JSON::ParserError
+        raise Error, invalid_settings_message
+      end
+
+      def valid_settings_shape?(settings)
+        return false unless settings.is_a?(Hash)
+
+        hooks = settings["hooks"]
+        return true if hooks.nil?
+        return false unless hooks.is_a?(Hash)
+
+        valid_post_tool_use?(hooks["PostToolUse"])
+      end
+
+      def valid_post_tool_use?(entries)
+        return true if entries.nil?
+
+        entries.is_a?(Array) && entries.all? { |entry| valid_hook_group?(entry) }
+      end
+
+      def valid_hook_group?(entry)
+        return false unless entry.is_a?(Hash)
+
+        hooks = entry["hooks"]
+        hooks.nil? || (hooks.is_a?(Array) && hooks.all?(Hash))
+      end
+
+      # Settings are validated before anything is copied, so reaching here means NOTHING was
+      # installed — including #{HOOK_REL}. The recovery therefore has to be "fix the settings and
+      # re-run", not "register the hook manually": the hook script does not exist yet, so pointing
+      # Claude at it would leave the advisory guardrail silently disabled.
+      def invalid_settings_message
+        "#{SETTINGS_REL} is not valid JSON for Claude settings, so it was left untouched and no " \
+          "guardrail files were installed (#{HOOK_REL} does not exist yet). Fix or remove " \
+          "#{SETTINGS_REL}, then re-run `rake react_on_rails:install_rsc_agent_guardrails` to " \
+          "install the hook and register it as a PostToolUse (#{HOOK_MATCHER}) command hook."
+      end
+
+      def hook_registered?(settings)
+        entries = Array(settings.dig("hooks", "PostToolUse"))
+        managed_hooks = entries.flat_map { |entry| Array(entry["hooks"]) }.select { |hook| managed_hook?(hook) }
+        return false unless managed_hooks.one? && registered_hook?(managed_hooks.first)
+
+        entries.any? do |entry|
+          entry["matcher"] == HOOK_MATCHER && Array(entry["hooks"]).include?(managed_hooks.first)
+        end
+      end
+
+      def add_hook(settings)
+        hooks = (settings["hooks"] ||= {})
+        post_tool_use = (hooks["PostToolUse"] ||= [])
+        post_tool_use.each do |candidate|
+          Array(candidate["hooks"]).reject! { |hook| managed_hook?(hook) }
+        end
+        entry = post_tool_use.find { |candidate| candidate["matcher"] == HOOK_MATCHER }
+        unless entry
+          entry = { "matcher" => HOOK_MATCHER, "hooks" => [] }
+          post_tool_use << entry
+        end
+        (entry["hooks"] ||= []) << { "type" => "command", "command" => HOOK_COMMAND, "args" => HOOK_ARGS }
+      end
+
+      def registered_hook?(hook)
+        hook["type"] == "command" && hook["command"] == HOOK_COMMAND && hook["args"] == HOOK_ARGS
+      end
+
+      def managed_hook?(hook)
+        registered_hook?(hook) || hook["command"] == LEGACY_HOOK_COMMAND
+      end
+    end
+  end
+end