tidewave 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e88c68fa913f5012d8fa2b69353e4d2d290a36e4a2ebbc4194ccb220990ce75
-  data.tar.gz: f132fbe9a0c4d15f4f2f91773af9cbaebadfacbb98aac2d8a6ceeeccdb1903eb
+  metadata.gz: d708afbfcf6d89cc1456bd7bcefdc660952571cda0c6635b8c6b14b8fa31d91e
+  data.tar.gz: da923b2f69608fe95eb11f76795cef1598f9cc24941afe50081afc4b76c66cfa
 SHA512:
-  metadata.gz: 37c5d8dfd49cb1fcb2d37302f0ea8ddf715262c6054405935fe3568741c50b65e26a2a6731dd64edb68791a2fd8bb58f20332a8119362c8949b18db8a1c82a07
-  data.tar.gz: 7bdd172eb19ef223ab972686d310f35a690331a5678467b22fb2d0bf70c401173784a47be2aa035e5bc704a602cb8e28ee7aaed1f6c18aff62ea743dd628a652
+  metadata.gz: 9b0eaa2a77690e4dda1720e5c2c84b02ea93d9b69955e2e430745da483d30014ba3fc5d59dc40c92b0ccdedd4413f4198012813a33f2332fd7ca08a9fac79fc1
+  data.tar.gz: 501103bf39a69932a408ebf9e455640fc8fb97a507163d6b4f42faf27aead8811927ecc249858978c8c5a46213dbe5b1d8635ade60817f546645ec99fa4c203a

data/README.md

@@ -6,17 +6,6 @@ assistant to your web framework runtime via [MCP](https://modelcontextprotocol.i
 
 [See our website](https://tidewave.ai) for more information.
 
-## Key Features
-
-Tidewave provides tools that allow your LLM of choice to:
-
-- inspect your application logs to help debugging errors
-- execute SQL queries and inspect your database
-- evaluate custom Ruby code in the context of your project
-- find Rubygems packages and source code locations
-
-and more.
-
 ## Installation
 
 You can install Tidewave by adding the `tidewave` gem to the development group in your Gemfile:
@@ -29,37 +18,47 @@ Tidewave will now run on the same port as your regular Rails application.
 In particular, the MCP is located by default at http://localhost:3000/tidewave/mcp.
 [You must configure your editor and AI assistants accordingly](https://hexdocs.pm/tidewave/mcp.html).
 
-## Configuration
+## Troubleshooting
 
-You may configure the `tidewave` using the following syntax:
+### Localhost requirement
+
+Tidewave expects your web application to be running on `localhost`. If you are not running on localhost, you may need to set some additional configuration. In particular, you must configure Tidewave to allow `allow_remote_access` and [optionally configure your Rails hosts](https://guides.rubyonrails.org/configuring.html#actiondispatch-hostauthorization). For example, in your `config/environments/development.rb`:
 
 ```ruby
-  config.tidewave.allowed_ips = [IPAddr.new("192.168.97.1")]
+config.hosts << "company.local"
+config.tidewave.allow_remote_access = true
 ```
 
-The following options are available:
-
-  * `:allowed_origins`
-
-  * `:localhost_only`
-
-  * `:allowed_ips`
+If you want to use Docker for development, you either need to enable the configuration above or automatically redirect the relevant ports, as done by [devcontainers](https://code.visualstudio.com/docs/devcontainers/containers). See our [containars](https://hexdocs.pm/tidewave/containers.html) guide for more information.
 
-You can read more about this options in [FastMCP](https://github.com/yjacquin/fast_mcp) README.
+### Content security policy
 
-## Considerations
+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.
 
 ### Production Environment
 
-Tidewave is a powerful tool that can help you develop your web application faster and more efficiently.
-However, it is important to note that Tidewave is not meant to be used in a production environment.
+Tidewave is a powerful tool that can help you develop your web application faster and more efficiently. However, it is important to note that Tidewave is not meant to be used in a production environment.
 
-Tidewave will raise an error if it is used in a production environment.
+Tidewave will raise an error if it is used in any environment where code reloading is disabled (which typically includes production).
 
 ### Web server requirements
 
 Tidewave currently requires a threaded web server like Puma.
 
+## Configuration
+
+You may configure `tidewave` using the following syntax:
+
+```ruby
+  config.tidewave.allow_remote_access = true
+```
+
+The following options are available:
+
+  * `:allow_remote_access` - Tidewave only allows requests from localhost by default, even if your server listens on other interfaces as well. If you trust your network and need to access Tidewave from a different machine, this configuration can be set to `true`
+
+  * `:preferred_orm` - which ORM to use, either `:active_record` (default) or `:sequel`
+
 ## Acknowledgements
 
 A thank you to Yorick Jacquin, for creating [FastMCP](https://github.com/yjacquin/fast_mcp) and implementing the initial version of this project.

data/lib/tidewave/configuration.rb

@@ -2,13 +2,14 @@
 
 module Tidewave
   class Configuration
-    attr_accessor :logger, :allowed_origins, :localhost_only, :allowed_ips
+    attr_accessor :logger, :allow_remote_access, :preferred_orm, :credentials, :client_url
 
     def initialize
-      @logger = Logger.new(STDOUT)
-      @allowed_origins = nil
-      @localhost_only = true
-      @allowed_ips = nil
+      @logger = nil
+      @allow_remote_access = true
+      @preferred_orm = :active_record
+      @credentials = {}
+      @client_url = "https://tidewave.ai"
     end
   end
 end

data/lib/tidewave/database_adapter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Tidewave
+  class DatabaseAdapter
+    class << self
+      def current
+        @current ||= create_adapter
+      end
+
+      def create_adapter
+        orm_type = Rails.application.config.tidewave.preferred_orm
+        case orm_type
+        when :active_record
+          require_relative "database_adapters/active_record"
+          DatabaseAdapters::ActiveRecord.new
+        when :sequel
+          require_relative "database_adapters/sequel"
+          DatabaseAdapters::Sequel.new
+        else
+          raise "Unknown preferred ORM: #{orm_type}"
+        end
+      end
+    end
+
+    def execute_query(query, arguments = [])
+      raise NotImplementedError, "Subclasses must implement execute_query"
+    end
+
+    def get_base_class
+      raise NotImplementedError, "Subclasses must implement get_base_class"
+    end
+  end
+end

data/lib/tidewave/database_adapters/active_record.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Tidewave
+  module DatabaseAdapters
+    class ActiveRecord < DatabaseAdapter
+      RESULT_LIMIT = 50
+
+      def execute_query(query, arguments = [])
+        conn = ::ActiveRecord::Base.connection
+
+        # Execute the query with prepared statement and arguments
+        if arguments.any?
+          result = conn.exec_query(query, "SQL", arguments)
+        else
+          result = conn.exec_query(query)
+        end
+
+        # Format the result
+        {
+          columns: result.columns,
+          rows: result.rows.first(RESULT_LIMIT),
+          row_count: result.rows.length,
+          adapter: conn.adapter_name,
+          database: database_name
+        }
+      end
+
+      def get_base_class
+        ::ActiveRecord::Base
+      end
+
+      private
+
+      def database_name
+        Rails.configuration.database_configuration.dig(Rails.env, "database")
+      end
+    end
+  end
+end

data/lib/tidewave/database_adapters/sequel.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Tidewave
+  module DatabaseAdapters
+    class Sequel < DatabaseAdapter
+      RESULT_LIMIT = 50
+
+      def execute_query(query, arguments = [])
+        db = ::Sequel::Model.db
+
+        # Execute the query with arguments
+        result = if arguments.any?
+          db.fetch(query, *arguments)
+        else
+          db.fetch(query)
+        end
+
+        # Convert to array of hashes and extract metadata
+        rows = result.all
+        columns = rows.first&.keys || []
+
+        # Format the result similar to ActiveRecord
+        {
+          columns: columns.map(&:to_s),
+          rows: rows.first(RESULT_LIMIT).map(&:values),
+          row_count: rows.length,
+          adapter: db.adapter_scheme.to_s.upcase,
+          database: db.opts[:database]
+        }
+      end
+
+      def get_base_class
+        ::Sequel::Model
+      end
+    end
+  end
+end

data/lib/tidewave/exceptions_middleware.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+class Tidewave::ExceptionsMiddleware
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    request = ActionDispatch::Request.new(env)
+    status, headers, body = @app.call(env)
+
+    exception = request.get_header("tidewave.exception")
+
+    if exception
+      formatted = format_exception_html(exception, request)
+      body, headers = append_body(body, headers, formatted)
+    end
+
+    [ status, headers, body ]
+  rescue => error
+    Rails.logger.error("Failure in Tidewave::ExceptionsMiddleware, message: #{error.message}")
+    raise error
+  end
+
+  private
+
+  def format_exception_html(exception, request)
+    backtrace = Rails.backtrace_cleaner.clean(exception.backtrace)
+
+    parameters = request_parameters(request)
+
+    text = exception.class.name.dup
+
+    if parameters["controller"]
+      text << " in #{parameters["controller"].camelize}Controller"
+
+      if parameters["action"]
+        text << "##{parameters["action"]}"
+      end
+    end
+
+    text << "\n\n## Message\n\n#{exception.message}"
+
+    if backtrace.any?
+      text << "\n\n## Backtrace\n\n#{backtrace.join("\n")}"
+    end
+
+    text << "\n\n"
+
+    text << <<~TEXT.chomp
+      ## Request info
+
+        * URI: #{request.base_url + request.path}
+        * Query string: #{request.query_string}
+
+      ## Session
+
+          #{request.session.to_hash.inspect}
+    TEXT
+
+    %Q(<textarea style="display: none;" data-tidewave-exception-info>#{ERB::Util.html_escape(text)}</textarea>)
+  end
+
+  def request_parameters(request)
+    request.parameters
+  rescue ActionController::BadRequest
+    {}
+  end
+
+  def append_body(body, headers, content)
+    new_body = "".dup
+
+    body.each { |part| new_body << part }
+    body.close if body.respond_to?(:close)
+
+    if position = new_body.rindex("</body>")
+      new_body.insert(position, content)
+    else
+      new_body << content
+    end
+
+    if headers[Rack::CONTENT_LENGTH]
+      headers[Rack::CONTENT_LENGTH] = new_body.bytesize.to_s
+    end
+
+    [ [ new_body ], headers ]
+  end
+end

data/lib/tidewave/file_tracker.rb

@@ -4,120 +4,99 @@ module Tidewave
   module FileTracker
     extend self
 
-    def project_files
-      `git --git-dir #{git_root}/.git ls-files --cached --others --exclude-standard`.split("\n")
+    def project_files(glob_pattern: nil, include_ignored: false)
+      args = [ "ls-files", "--cached", "--others" ]
+      args << "--exclude-standard" unless include_ignored
+      args << glob_pattern if glob_pattern
+      `git #{args.join(" ")}`.split("\n")
     end
 
-    def read_file(path)
-      validate_path_access!(path)
-
-      # Retrieve the full path
+    def read_file(path, line_offset: 0, count: nil)
       full_path = file_full_path(path)
+      # Explicitly read the mtime first to avoid race conditions
+      mtime = File.mtime(full_path).to_i
+      content = File.read(full_path)
 
-      # Record the file as read
-      record_read(path)
+      if line_offset > 0 || count
+        lines = content.lines
+        start_idx = [ line_offset, 0 ].max
+        count = (count || lines.length)
+        selected_lines = lines[start_idx, count]
+        content = selected_lines ? selected_lines.join : ""
+      end
 
-      # Read and return the file contents
-      File.read(full_path)
+      [ mtime, content ]
     end
 
     def write_file(path, content)
-      validate_path_access!(path, validate_existence: false)
-      # Retrieve the full path
+      validate_ruby_syntax!(content) if ruby_file?(path)
       full_path = file_full_path(path)
 
-      dirname = File.dirname(full_path)
-
       # Create the directory if it doesn't exist
+      dirname = File.dirname(full_path)
       FileUtils.mkdir_p(dirname)
 
-      # Write the file contents
+      # Write and return the file contents
       File.write(full_path, content)
-
-      # Read and return the file contents
-      read_file(path)
+      content
     end
 
     def file_full_path(path)
-      File.join(git_root, path)
-    end
-
-    def git_root
-      @git_root ||= `git rev-parse --show-toplevel`.strip
+      File.expand_path(path, Rails.root)
     end
 
     def validate_path_access!(path, validate_existence: true)
-      raise ArgumentError, "File path must not start with '..'" if path.start_with?("..")
+      raise ArgumentError, "File path must not contain '..'" if path.include?("..")
 
       # Ensure the path is within the project
       full_path = file_full_path(path)
 
       # Verify the file is within the project directory
-      raise ArgumentError, "File path must be within the project directory" unless full_path.start_with?(git_root)
+      unless full_path.start_with?(Rails.root.to_s + File::SEPARATOR)
+        raise ArgumentError, "File path must be within the project directory"
+      end
 
       # Verify the file exists
-      raise ArgumentError, "File not found: #{path}" unless File.exist?(full_path) && validate_existence
+      if validate_existence && !File.exist?(full_path)
+        raise ArgumentError, "File not found: #{path}"
+      end
 
       true
     end
 
-    def validate_path_is_editable!(path)
+    def validate_path_is_editable!(path, atime)
       validate_path_access!(path)
-      validate_path_has_been_read_since_last_write!(path)
+      validate_path_has_been_read_since_last_write!(path, atime)
 
       true
     end
 
-    def validate_path_is_writable!(path)
+    def validate_path_is_writable!(path, atime)
       validate_path_access!(path, validate_existence: false)
-      validate_path_has_been_read_since_last_write!(path)
+      validate_path_has_been_read_since_last_write!(path, atime)
 
       true
     end
 
-    def validate_path_has_been_read_since_last_write!(path)
-      raise ArgumentError, "File has been modified since last read, please read the file again" unless file_was_read_since_last_write?(path)
+    private
 
-      true
+    def ruby_file?(path)
+      [ ".rb", ".rake", ".gemspec" ].include?(File.extname(path)) ||
+        [ "Gemfile" ].include?(File.basename(path))
     end
 
-    # Record when a file was read
-    def record_read(path)
-      file_records[path] = Time.now
+    def validate_ruby_syntax!(content)
+      RubyVM::AbstractSyntaxTree.parse(content)
+    rescue SyntaxError => e
+      raise "Invalid Ruby syntax: #{e.message}"
     end
 
+    def validate_path_has_been_read_since_last_write!(path, atime)
+      if atime && File.mtime(file_full_path(path)).to_i > atime
+        raise ArgumentError, "File has been modified since last read, please read the file again"
+      end
 
-    def file_was_read_since_last_write?(path)
-      file_was_read?(path) && last_read_at(path) >= last_modified_at(path)
-    end
-
-    # Check if a file has been read
-    def file_was_read?(path)
-      file_records.key?(path)
-    end
-
-    # Check if a file exists
-    def file_exists?(path)
-      File.exist?(file_full_path(path))
-    end
-
-    # Get the timestamp when a file was last read
-    def last_read_at(path)
-      file_records[path]
-    end
-
-    def last_modified_at(path)
-      File.mtime(file_full_path(path))
-    end
-
-    # Reset all tracked files (useful for testing)
-    def reset
-      @file_records = {}
-    end
-
-    # Hash mapping file paths to their read records
-    def file_records
-      @file_records ||= {}
+      true
     end
   end
 end

data/lib/tidewave/middleware.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "open3"
+require "ipaddr"
+require "fast_mcp"
+require "rack/request"
+require "active_support/core_ext/class"
+require "active_support/core_ext/object/blank"
+require "json"
+require "erb"
+
+class Tidewave::Middleware
+  TIDEWAVE_ROUTE = "tidewave".freeze
+  EMPTY_ROUTE = "empty".freeze
+  SSE_ROUTE = "mcp".freeze
+  MESSAGES_ROUTE = "mcp/message".freeze
+  SHELL_ROUTE = "shell".freeze
+
+  INVALID_IP = <<~TEXT.freeze
+    For security reasons, Tidewave does not accept remote connections by default.
+
+    If you really want to allow remote connections, set `config.tidewave.allow_remote_access = true`.
+  TEXT
+
+  def initialize(app, config)
+    @allow_remote_access = config.allow_remote_access
+    @client_url = config.client_url
+    @project_name = Rails.application.class.module_parent.name
+
+    @app = FastMcp.rack_middleware(app,
+      name: "tidewave",
+      version: Tidewave::VERSION,
+      path_prefix: "/" + TIDEWAVE_ROUTE,
+      messages_route: MESSAGES_ROUTE,
+      sse_route: SSE_ROUTE,
+      logger: config.logger || Logger.new(Rails.root.join("log", "tidewave.log")),
+      # Rails runs the HostAuthorization in dev, so we skip this
+      allowed_origins: [],
+      # We validate this one in Tidewave::Middleware
+      localhost_only: false
+    ) do |server|
+      server.filter_tools do |request, tools|
+        if request.params["include_fs_tools"] != "true"
+          tools.reject { |tool| tool.tags.include?(:file_system_tool) }
+        else
+          tools
+        end
+      end
+
+      server.register_tools(*Tidewave::Tools::Base.descendants)
+    end
+  end
+
+  def call(env)
+    request = Rack::Request.new(env)
+    path = request.path.split("/").reject(&:empty?)
+
+    if path[0] == TIDEWAVE_ROUTE
+      return forbidden(INVALID_IP) unless valid_client_ip?(request)
+
+      # The MCP routes are handled downstream by FastMCP
+      case [ request.request_method, path ]
+      when [ "GET", [ TIDEWAVE_ROUTE ] ]
+        return home(request)
+      when [ "GET", [ TIDEWAVE_ROUTE, EMPTY_ROUTE ] ]
+        return empty(request)
+      when [ "POST", [ TIDEWAVE_ROUTE, SHELL_ROUTE ] ]
+        return shell(request)
+      end
+    end
+
+    @app.call(env)
+  end
+
+  private
+
+  def home(request)
+    config = {
+      "project_name" => @project_name,
+      "framework_type" => "rails",
+      "tidewave_version" => Tidewave::VERSION
+    }
+
+    html = <<~HTML
+      <html>
+        <head>
+          <meta charset="UTF-8" />
+          <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+          <meta name="tidewave:config" content="#{ERB::Util.html_escape(JSON.generate(config))}" />
+          <script type="module" src="#{@client_url}/tc/tc.js"></script>
+        </head>
+        <body></body>
+      </html>
+    HTML
+
+    [ 200, { "Content-Type" => "text/html" }, [ html ] ]
+  end
+
+  def empty(request)
+    html = ""
+    [ 200, { "Content-Type" => "text/html" }, [ html ] ]
+  end
+
+  def forbidden(message)
+    Rails.logger.warn(message)
+    [ 403, { "Content-Type" => "text/plain" }, [ message ] ]
+  end
+
+  def shell(request)
+    body = request.body.read
+    return [ 400, { "Content-Type" => "text/plain" }, [ "Command body is required" ] ] if body.blank?
+
+    begin
+      parsed_body = JSON.parse(body)
+      cmd = parsed_body["command"]
+      return [ 400, { "Content-Type" => "text/plain" }, [ "Command field is required" ] ] if cmd.blank?
+    rescue JSON::ParserError
+      return [ 400, { "Content-Type" => "text/plain" }, [ "Invalid JSON in request body" ] ]
+    end
+
+    response = Rack::Response.new
+    response.status = 200
+    response.headers["Content-Type"] = "text/plain"
+
+    response.finish do |res|
+      begin
+        Open3.popen3(*cmd) do |stdin, stdout, stderr, wait_thr|
+          stdin.close
+
+          # Merge stdout and stderr streams
+          ios = [ stdout, stderr ]
+
+          until ios.empty?
+            ready = IO.select(ios, nil, nil, 0.1)
+            next unless ready
+
+            ready[0].each do |io|
+              begin
+                data = io.read_nonblock(4096)
+                if data
+                  # Write binary chunk: type (0 for data) + 4-byte length + data
+                  chunk = [ 0, data.bytesize ].pack("CN") + data
+                  res.write(chunk)
+                end
+              rescue IO::WaitReadable
+                # No data available right now
+              rescue EOFError
+                # Stream ended
+                ios.delete(io)
+              end
+            end
+          end
+
+          # Wait for process to complete and get exit status
+          exit_status = wait_thr.value.exitstatus
+          status_json = JSON.generate({ status: exit_status })
+          # Write binary chunk: type (1 for status) + 4-byte length + JSON data
+          chunk = [ 1, status_json.bytesize ].pack("CN") + status_json
+          res.write(chunk)
+        end
+      rescue => e
+        error_json = JSON.generate({ status: 213 })
+        chunk = [ 1, error_json.bytesize ].pack("CN") + error_json
+        res.write(chunk)
+      end
+    end
+  end
+
+  def valid_client_ip?(request)
+    return true if @allow_remote_access
+
+    ip = request.ip
+    return false unless ip
+
+    addr = IPAddr.new(ip)
+
+    addr.loopback? ||
+    addr == IPAddr.new("127.0.0.1") ||
+    addr == IPAddr.new("::1") ||
+    addr == IPAddr.new("::ffff:127.0.0.1")  # IPv4-mapped IPv6
+  end
+end