Toolbar and /tidewave/app (#106)

Author: josevalim

README.md

@@ -12,9 +12,7 @@ Your agent will be able to use this MCP server to talk to your running Rails app
 
 This MCP server is an open-source component of [Tidewave](https://tidewave.ai), the agentic development environment for Rails and Phoenix.
 
-You can use this project as a standalone MCP server or integrated with the [Tidewave product](https://tidewave.ai).
-
-To use it as a standalone MCP server, follow the installation instructions below.
+You can use this project as a standalone MCP server or integrated with the [Tidewave product](https://tidewave.ai) by following the instructions below.
 
 ## Installation
 
@@ -117,6 +115,10 @@ Also, because it resolves the location from your running app instead of parsing
 
 ## Troubleshooting
 
+### The Tidewave toolbar is missing
+
+This may happen if you are compressing your responses (gzip, brotli, etc) after the Tidewave middleware runs. Use `bin/rails middleware` and make sure Tidewave comes after `Rack::Deflater` or similar. Also look into your browser and terminal logs for any errors.
+
 ### Using multiple hosts/subdomains
 
 If you are using multiple hosts/subdomains during development, you must use `*.localhost`, as such domains are considered secure by browsers. Additionally, add the following to `config/initializers/development.rb`:
@@ -135,7 +137,7 @@ The above will allow your application to run embedded within Tidewave across mul
 
 ### Content security policy
 
-If you have enabled Content-Security-Policy, Tidewave will automatically enable "unsafe-eval" under `script-src` in order for contextual browser testing to work correctly. It also disables the `frame-ancestors` directive.
+If you have enabled Content-Security-Policy, Tidewave will automatically enable "unsafe-eval" under `script-src` in order for contextual browser testing to work correctly. It also disables the `frame-ancestors` directive. This is done only in the environments that Tidewave is loadead (development by default).
 
 ### Production Environment
 
@@ -161,6 +163,8 @@ The following config is available:
 
   * `team` - set your Tidewave Team configuration, such as `config.tidewave.team = { id: "my-company" }`
 
+  * `toolbar` - controls whether the Tidewave toolbar is injected into HTML pages. Defaults to `true`
+
 ## Acknowledgements
 
 A thank you to Yorick Jacquin for the initial version of this project.

lib/tidewave.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "cgi"
 require "ipaddr"
 require "json"
 require "pathname"
@@ -29,9 +30,50 @@ module Tools
 end
 
 class Tidewave
+  class ToolbarBody
+    def initialize(body, toolbar)
+      @body = body
+      @toolbar = toolbar
+      @closed = false
+    end
+
+    def each
+      return enum_for(:each) unless block_given?
+
+      pending = +""
+      injected = false
+
+      @body.each do |part|
+        if injected
+          yield part
+        else
+          pending << part
+
+          if closing_head = pending.downcase.index("</head>")
+            toolbar = @toolbar.dup.force_encoding(pending.encoding)
+            output = pending.insert(closing_head, toolbar)
+            pending = nil
+            injected = true
+            yield output
+          end
+        end
+      end
+
+      yield pending unless injected || pending.empty?
+    end
+
+    def close
+      return if @closed
+
+      @closed = true
+      @body.close if @body.respond_to?(:close)
+    end
+  end
+
   TIDEWAVE_ROUTE = "tidewave".freeze
   MCP_ROUTE = "mcp".freeze
   CONFIG_ROUTE = "config".freeze
+  APP_ROUTE = "app".freeze
   UPLOAD_ROUTE = "upload".freeze
   PROTOCOL_VERSION = "2025-03-26".freeze
   MAX_UPLOAD_SIZE = 10_000_000
@@ -47,12 +89,18 @@ class Tidewave
 
   INVALID_ORIGIN = "For security reasons, Tidewave does not accept requests with an origin header for this endpoint.".freeze
   INVALID_UPLOAD = "Bad Request: missing or invalid file parameter".freeze
+  ENCODED_HTML_WARNING = <<~TEXT.freeze
+    Tidewave could not inject the toolbar because the HTML response is encoded.
+
+    If you use Rack::Deflater or another compression middleware, place it before Tidewave in the middleware stack.
+  TEXT
 
   DEFAULT_OPTIONS = {
     allow_remote_access: false,
     client_url: "https://tidewave.ai",
     framework_type: "rack",
-    team: {}
+    team: {},
+    toolbar: true
   }.freeze
 
   def initialize(app, options = {})
@@ -77,6 +125,8 @@ def call(env)
       case [ request.request_method, path ]
       when [ "GET", [ TIDEWAVE_ROUTE ] ]
         home_endpoint(request)
+      when [ "GET", [ TIDEWAVE_ROUTE, APP_ROUTE ] ]
+        app_endpoint(request)
       when [ "GET", [ TIDEWAVE_ROUTE, CONFIG_ROUTE ] ]
         config_endpoint(request)
       when [ "POST", [ TIDEWAVE_ROUTE, MCP_ROUTE ] ]
@@ -89,7 +139,7 @@ def call(env)
         path == [ TIDEWAVE_ROUTE, MCP_ROUTE ] ? method_not_allowed() : not_found()
       end
     else
-      strip_x_frame_options(@app.call(env))
+      inject_toolbar(request, strip_x_frame_options(@app.call(env)))
     end
   end
 
@@ -118,6 +168,25 @@ def home_endpoint(_request)
     [ 200, response_headers("text/html", body), [ body ] ]
   end
 
+  def app_endpoint(_request)
+    client_url = @options[:client_url].to_s.sub(%r{/\z}, "")
+    body = <<~HTML
+      <!DOCTYPE html>
+      <html>
+        <head>
+          <meta charset="UTF-8" />
+          <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+          <script type="module" src="#{client_url}/tc/control.js"></script>
+        </head>
+        <body></body>
+      </html>
+    HTML
+
+    headers = response_headers("text/html", body)
+    headers["content-security-policy"] = "base-uri 'self'; frame-ancestors 'self';"
+    [ 200, headers, [ body ] ]
+  end
+
   def config_endpoint(request)
     json_response(config_data(request), headers: { "access-control-allow-origin" => "*" })
   end
@@ -167,10 +236,70 @@ def config_data(request)
       "team" => @options[:team] || {},
       "tidewave_version" => VERSION,
       "local_port" => local_port(request),
-      "tmp_dir" => TMP_DIR
+      "tmp_dir" => TMP_DIR,
+      "wsl_distro" => ENV["WSL_DISTRO_NAME"]
     }
   end
 
+  def inject_toolbar(request, response)
+    status, headers, body = response
+    return response if @options[:toolbar] == false || !html_response?(headers)
+
+    if encoded_response?(headers)
+      warn_encoded_html
+      return response
+    end
+
+    return response unless body.respond_to?(:each)
+
+    delete_response_header(headers, "content-length")
+    delete_response_header(headers, "etag")
+    [ status, headers, ToolbarBody.new(body, toolbar_html(request)) ]
+  end
+
+  def html_response?(headers)
+    content_types = Array(response_header(headers, "content-type"))
+
+    content_types.any? { |content_type| content_type.to_s.downcase.start_with?("text/html") }
+  end
+
+  def encoded_response?(headers)
+    Array(response_header(headers, "content-encoding")).any? do |content_encoding|
+      content_encoding.to_s.split(",").any? do |encoding|
+        !encoding.strip.empty? && encoding.strip.downcase != "identity"
+      end
+    end
+  end
+
+  def response_header(headers, name)
+    key = headers.keys.find { |header| header.downcase == name }
+    headers[key] if key
+  end
+
+  def delete_response_header(headers, name)
+    headers.delete_if { |header, _value| header.downcase == name }
+  end
+
+  def warn_encoded_html
+    return if @warned_encoded_html
+
+    @warned_encoded_html = true
+    @logger&.warn(ENCODED_HTML_WARNING)
+  end
+
+  def toolbar_html(request)
+    client_url = @options[:client_url].to_s.sub(%r{/\z}, "")
+    payload = {
+      "tidewave" => config_data(request),
+      "root" => @root.to_s
+    }
+
+    <<~HTML
+      <meta name="tidewave:config" content="#{CGI.escapeHTML(JSON.generate(payload))}" />
+      <script async type="module" src="#{client_url}/tc/toolbar.js"></script>
+    HTML
+  end
+
   def upload_endpoint(request)
     return text_response(400, INVALID_UPLOAD) if upload_too_large?(request)
 
@@ -232,6 +361,7 @@ def response_headers(content_type, body)
   def origin_allowed_path?(path)
     [
       [ TIDEWAVE_ROUTE ],
+      [ TIDEWAVE_ROUTE, APP_ROUTE ],
       [ TIDEWAVE_ROUTE, CONFIG_ROUTE ],
       [ TIDEWAVE_ROUTE, UPLOAD_ROUTE ]
     ].include?(path)

lib/tidewave/configuration.rb

@@ -2,7 +2,7 @@
 
 class Tidewave
   class Configuration
-    attr_accessor :logger, :allow_remote_access, :preferred_orm, :dev, :client_url, :team, :logger_middleware
+    attr_accessor :logger, :allow_remote_access, :preferred_orm, :dev, :client_url, :team, :logger_middleware, :toolbar
 
     def initialize
       # Rails has a hosts middleware which already checks for this
@@ -13,6 +13,7 @@ def initialize
       @client_url = "https://tidewave.ai"
       @team = {}
       @logger_middleware = nil
+      @toolbar = true
     end
   end
 end

lib/tidewave/railtie.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "logger"
+require "uri"
 require "tidewave/configuration"
 require "tidewave/exceptions_middleware"
 require "tidewave/quiet_requests_middleware"
@@ -24,6 +25,7 @@ class Railtie < Rails::Railtie
         framework_type: "rails",
         project_name: app.class.module_parent.name,
         team: tidewave_config.team,
+        toolbar: tidewave_config.toolbar,
         logger: tidewave_config.logger || Rails.logger,
         root: Rails.root,
         log_file: Rails.root.join("log", "#{Rails.env}.log"),
@@ -35,11 +37,21 @@ class Railtie < Rails::Railtie
         # If the user configured CSP, we need to alter it in dev
         # to allow TC to run browser_eval.
         app.config.content_security_policy.try do |content_security_policy|
-          content_security_policy.directives["script-src"].try do |script_src|
+          directives = content_security_policy.directives
+          script_src = directives["script-src"] || directives["default-src"]&.dup
+          client_origin = URI.parse(tidewave_config.client_url.to_s).origin
+
+          script_src.try do
             script_src << "'unsafe-eval'" unless script_src.include?("'unsafe-eval'")
+            script_src << client_origin unless script_src.include?(client_origin)
+            directives["script-src"] = script_src
+          end
+
+          directives["script-src-elem"].try do |script_src_elem|
+            script_src_elem << client_origin unless script_src_elem.include?(client_origin)
           end
 
-          content_security_policy.directives.delete("frame-ancestors")
+          directives.delete("frame-ancestors")
         end
       end
     end

test/rack_lint_test.rb

@@ -30,6 +30,19 @@ def test_config_endpoint_is_rack_conformant
     assert_lint_ok { @mock.get("/tidewave/config") }
   end
 
+  def test_app_endpoint_is_rack_conformant
+    assert_lint_ok { @mock.get("/tidewave/app") }
+  end
+
+  def test_toolbar_response_is_rack_conformant
+    downstream = ->(_env) { [ 200, { "content-type" => "text/html" }, [ "<html><head></head></html>" ] ] }
+    app = Rack::Lint.new(Tidewave.new(downstream, project_name: "lint", allow_remote_access: true))
+
+    response = Rack::MockRequest.new(app).get("/")
+
+    assert_includes response.body, "/tc/toolbar.js"
+  end
+
   def test_mcp_post_is_rack_conformant
     assert_lint_ok { @mock.post("/tidewave/mcp", input: @init) }
   end

test/railtie_test.rb

@@ -20,10 +20,17 @@ def test_railtie_boots_and_inserts_middleware_with_expected_options
     assert_equal "rails", options[:framework_type]
     assert_equal "TidewaveRailtieTestApp", options[:project_name]
     assert_equal({ id: "dashbit" }, options[:team])
+    assert_equal true, options[:toolbar]
     assert_same TidewaveRailtieTestApp::LOGGER, options[:logger]
     assert_equal TidewaveRailtieTestApp::ROOT, options[:root]
     assert_equal TidewaveRailtieTestApp::ROOT.join("log", "#{Rails.env}.log"), options[:log_file]
     assert_equal :sequel, options[:orm_adapter]
     assert_kind_of Proc, options[:before_reload]
+
+    directives = app.config.content_security_policy.directives
+    assert_equal [ "'self'" ], directives["default-src"]
+    assert_equal [ "'self'", "'unsafe-eval'", "https://example.test" ], directives["script-src"]
+    assert_equal [ "'self'", "https://example.test" ], directives["script-src-elem"]
+    refute directives.key?("frame-ancestors")
   end
 end

test/test_helper.rb

@@ -31,6 +31,11 @@ class Application < Rails::Application
     config.tidewave.preferred_orm = :sequel
     config.tidewave.logger = LOGGER
     config.tidewave.logger_middleware = ActionDispatch::ShowExceptions
+    config.content_security_policy do |policy|
+      policy.default_src :self
+      policy.frame_ancestors :self
+      policy.script_src_elem :self
+    end
   end
 end