tidewave 0.5.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c64d42ec2ee75f35b02997081d24e69fe547d8b9a20a230daeb1d1995a30cd0a
-  data.tar.gz: 74e1cc3e89cdea2b1d4701990ca3fbe3b4b3a5c828735bef5251c91a1d8c074a
+  metadata.gz: d8aec0fffb76b0c91651452a2d8e2b1adc3fe37681a0c778c01a4762602985ed
+  data.tar.gz: d0f6abae17bcc8281baed3f3db784b0243186c5008a8866a612e42bda4333e14
 SHA512:
-  metadata.gz: a2cf21787f51875cbec78b12b5800c7f03b8d516360fd960110f8717dc762f47e58f4f7a4b243c3f0120e254075f17495e86d6c3538d22dd8abe6ac046d3fc6d
-  data.tar.gz: 789f139be709d1bc9a0d55b8cb661b9212b3ce2b4fa546d2c644b3a676a6a2843687407e2efdc87c8a0785290c2aab1806693b07698cd71f9fb9e7f130714786
+  metadata.gz: 8b683cb4a188e66e456078a39467a10ff6bc9aa1ac3b3f2e92338eadf5cbe1b0a693e6d80dd32d6e8dfdb167dd0b83af1d1183c442fc6d8348beb036180e05ba
+  data.tar.gz: b3366af6bdd77c9312e8e6d70e56d898b02f75555f9b1932fea379bdb36621a8381f31df8696f86f7a6a5604885ae0ded2f22ee51a9bf323e80c7c7e52422c99

data/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.

data/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 @@ class Tidewave
       @client_url = "https://tidewave.ai"
       @team = {}
       @logger_middleware = nil
+      @toolbar = true
     end
   end
 end

data/lib/tidewave/magic_bytes.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class Tidewave
+  module MagicBytes
+    module_function
+
+    def type(bytes)
+      case bytes
+      when /\A\xFF\xD8\xFF/n
+        :jpg
+      when /\A\x89PNG\r\n\x1A\n/n
+        :png
+      when /\A\x1A\x45\xDF\xA3/n
+        bytes.include?("webm") ? :webm : :unknown
+      else
+        :unknown
+      end
+    end
+  end
+end

data/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 Tidewave
         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 Tidewave
         # 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

data/lib/tidewave/tools/execute_sql_query.rb

@@ -48,6 +48,17 @@ class Tidewave::Tools::ExecuteSqlQuery < Tidewave::Tool
   def call(arguments_hash)
     query = arguments_hash.fetch("query")
     arguments = arguments_hash.fetch("arguments", [])
-    @database_adapter.execute_query(query, arguments)
+    result = @database_adapter.execute_query(query, arguments)
+
+    preamble = if result[:row_count] > result[:rows].length
+      <<~TEXT
+        Query returned #{result[:row_count]} rows. Only the first #{result[:rows].length} rows are included in the result. Use your database's pagination syntax, such as LIMIT + OFFSET, to show more rows if applicable.
+
+      TEXT
+    else
+      ""
+    end
+
+    preamble + result.inspect
   end
 end

data/lib/tidewave/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Tidewave
-  VERSION = "0.5.2"
+  VERSION = "0.8.0"
 end

data/lib/tidewave.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
+require "fileutils"
+require "cgi"
 require "ipaddr"
 require "json"
+require "pathname"
 require "rack/request"
+require "uri"
 require "tidewave/version"
 require "tidewave/tool"
 require "tidewave/database_adapter"
+require "tidewave/magic_bytes"
 require "tidewave/railtie" if defined?(Rails::Railtie)
 
 class Tidewave
@@ -25,10 +30,56 @@ Dir[gem_tools_path].sort.each do |file|
 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
+  ALLOWED_UPLOAD_CONTENT_TYPES = [ "image/png", "image/jpeg", "video/webm" ].freeze
+  ALLOWED_UPLOAD_TYPES = [ "screenshot", "recording" ].freeze
+  TMP_DIR = "tmp".freeze
 
   INVALID_IP = <<~TEXT.freeze
     For security reasons, Tidewave does not accept remote connections by default.
@@ -37,12 +88,19 @@ class Tidewave
   TEXT
 
   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 = {})
@@ -51,6 +109,7 @@ class Tidewave
     raise ArgumentError, "project_name is required" if @options[:project_name].to_s.empty?
 
     @logger = @options[:logger]
+    @root = @options[:root] ? Pathname.new(@options[:root].to_s) : Pathname.pwd
     @tools = build_tool_registry
   end
 
@@ -60,24 +119,27 @@ class Tidewave
 
     if path[0] == TIDEWAVE_ROUTE
       return forbidden(INVALID_IP) unless valid_client_ip?(request)
-      if request.get_header("HTTP_ORIGIN") && !origin_allowed_path?(path)
-        return forbidden(INVALID_ORIGIN)
-      end
+
+      return forbidden(INVALID_ORIGIN) if request.get_header("HTTP_ORIGIN") && !origin_allowed_path?(path)
 
       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 ] ]
         mcp_endpoint(request)
+      when [ "POST", [ TIDEWAVE_ROUTE, UPLOAD_ROUTE ] ]
+        upload_endpoint(request)
       else
         # The MCP Streamable HTTP transport requires the MCP endpoint to answer
         # non-POST methods with 405 (GET without SSE support, DELETE, etc.)
         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
 
@@ -106,6 +168,25 @@ class Tidewave
     [ 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
@@ -154,10 +235,92 @@ class Tidewave
       "orm_adapter" => @options[:orm_adapter],
       "team" => @options[:team] || {},
       "tidewave_version" => VERSION,
-      "local_port" => local_port(request)
+      "local_port" => local_port(request),
+      "tmp_dir" => TMP_DIR
     }
   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,
+      "wsl_distro" => ENV["WSL_DISTRO_NAME"],
+      "framework" => {}
+    }
+
+    <<~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)
+
+    params = request.POST
+    type = params["type"]
+    upload = normalize_upload(params["file"])
+
+    unless ALLOWED_UPLOAD_TYPES.include?(type) && allowed_upload?(upload)
+      return text_response(400, INVALID_UPLOAD)
+    end
+
+    FileUtils.mkdir_p(upload_dir(type))
+    destination = upload_path(type, upload[:filename])
+    FileUtils.cp(upload[:path], destination)
+
+    json_response({ "status" => "ok", "path" => relative_path_from_root(destination) })
+  rescue ArgumentError
+    text_response(400, INVALID_UPLOAD)
+  end
+
   def json_response(payload, status: 200, headers: {})
     body = JSON.generate(payload)
     [ status, response_headers("application/json", body).merge(headers), [ body ] ]
@@ -197,7 +360,12 @@ class Tidewave
   end
 
   def origin_allowed_path?(path)
-    path == [ TIDEWAVE_ROUTE ] || path == [ TIDEWAVE_ROUTE, CONFIG_ROUTE ]
+    [
+      [ TIDEWAVE_ROUTE ],
+      [ TIDEWAVE_ROUTE, APP_ROUTE ],
+      [ TIDEWAVE_ROUTE, CONFIG_ROUTE ],
+      [ TIDEWAVE_ROUTE, UPLOAD_ROUTE ]
+    ].include?(path)
   end
 
   def local_port(request)
@@ -220,6 +388,67 @@ class Tidewave
     false
   end
 
+  def upload_too_large?(request)
+    request.content_length && request.content_length.to_i > MAX_UPLOAD_SIZE
+  end
+
+  def normalize_upload(upload)
+    case upload
+    when Hash
+      tempfile = upload[:tempfile] || upload["tempfile"]
+      {
+        filename: upload[:filename] || upload["filename"],
+        content_type: upload[:type] || upload["type"],
+        path: tempfile&.path
+      }
+    else
+      return {} unless upload.respond_to?(:original_filename) && upload.respond_to?(:content_type)
+
+      {
+        filename: upload.original_filename,
+        content_type: upload.content_type,
+        path: upload.tempfile&.path
+      }
+    end
+  end
+
+  def allowed_upload?(upload)
+    ALLOWED_UPLOAD_CONTENT_TYPES.include?(upload[:content_type].to_s.split(";").first) &&
+      upload[:path] &&
+      Tidewave::MagicBytes.type(File.binread(upload[:path], 128)) != :unknown
+  end
+
+  def upload_dir(type)
+    @root.join(TMP_DIR, "tidewave", folder_for_upload_type(type)).to_s
+  end
+
+  def upload_path(type, filename)
+    filename = filename.to_s
+
+    unless filename.match?(/\A[A-Za-z0-9_.-]+\z/) && !filename.include?("..")
+      raise ArgumentError, "filename must only contain numbers, letters, hyphens, and underscores: #{filename}"
+    end
+
+    unless [ ".png", ".jpg", ".jpeg", ".webm" ].include?(File.extname(filename).downcase)
+      raise ArgumentError, "filename must have a valid extension (.png, .jpg, .jpeg, .webm): #{filename}"
+    end
+
+    File.join(upload_dir(type), filename)
+  end
+
+  def folder_for_upload_type(type)
+    case type
+    when "screenshot"
+      "screenshots"
+    when "recording"
+      "recordings"
+    end
+  end
+
+  def relative_path_from_root(path)
+    Pathname.new(path).relative_path_from(@root).to_s
+  end
+
   def validate_jsonrpc_message(message)
     return "Message must be a JSON object" unless message.is_a?(Hash)
     return "Invalid JSON-RPC version" unless message["jsonrpc"] == "2.0"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tidewave
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.8.0
 platform: ruby
 authors:
 - Yorick Jacquin
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-09 00:00:00.000000000 Z
+date: 2026-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -41,6 +41,7 @@ files:
 - lib/tidewave/database_adapters/active_record.rb
 - lib/tidewave/database_adapters/sequel.rb
 - lib/tidewave/exceptions_middleware.rb
+- lib/tidewave/magic_bytes.rb
 - lib/tidewave/quiet_requests_middleware.rb
 - lib/tidewave/railtie.rb
 - lib/tidewave/tool.rb