tidewave 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3375b13a00fb5b052a2bea5c6b720056379f16a26cc984ffde2973d2d2fca90
-  data.tar.gz: b5d7c9d2290e2273116712116fcb8336ddbc4009be187ca0413ec3c727b33e6b
+  metadata.gz: d75b5659655095637ad8830051ef50f06e018339520d093c51854cec9c320fd7
+  data.tar.gz: 9325b6a4ea7ac4e1444a677bd1dc785bc6f8046e8492a5d1b70267c9424ca9a3
 SHA512:
-  metadata.gz: 6ad6d175fef2e61d40ab97de1bbf36bfaf3f37137ee7d54d6cc1f7987096e105e37381376e6f8263b70b31795065824b459225512d62e9ae5615c9dc098a8b2d
-  data.tar.gz: 2535c2570a69f70114705b2ec13f708b17bae00aefcaae504c97323c2c07edb3686a142d40f6a85f42a7619754f93fb8cbcd7267edcbb349fc621004f15c3ae2
+  metadata.gz: 9fe7d353f945a3a3735dfdd56486188df12034736c2ac78561dca478b05b6f15fba9608dd8e8209f3d9a66659f4908c2814ec65ccdf13030f56b1387a9190fde
+  data.tar.gz: 6782f79c55813d99d5cffeb973812116aaf581570119de0ebcd739d2f65d1aa0fbc3ed3bc1cc1d478ec0b30ac18fbc2ab9db6037df18ec433b8ef50cce7eb947

data/README.md

@@ -2,11 +2,17 @@
 
 Tidewave is the coding agent for full-stack web app development. Integrate Claude Code, OpenAI Codex, and other agents with your web app and web framework at every layer, from UI to database. [See our website](https://tidewave.ai) for more information.
 
-This project can also be used as a standalone Model Context Protocol server for your editors.
+This project can also be used as [a standalone Model Context Protocol server](https://hexdocs.pm/tidewave/mcp.html).
 
 ## Installation
 
-You can install Tidewave by adding the `tidewave` gem to the development group in your Gemfile:
+You can install Tidewave by running:
+
+```shell
+bundle add tidewave --group development
+```
+
+or by manully adding the `tidewave` gem to the development group in your Gemfile:
 
 ```ruby
 gem "tidewave", group: :development
@@ -14,30 +20,41 @@ gem "tidewave", group: :development
 
 Now make sure [Tidewave is installed](https://hexdocs.pm/tidewave/installation.html) and you are ready to connect Tidewave to your app.
 
+## Development
+
+Run the Minitest suite with:
+
+```shell
+bundle exec ruby -Itest test/all_test.rb
+```
+
 ## Troubleshooting
 
-### Content security policy
+### Using multiple hosts/subdomains
 
-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 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`:
 
-### Production Environment
+```ruby
+config.session_store :cookie_store,
+  key: "__your_app_session",
+  same_site: :none,
+  secure: true,
+  assume_ssl: true
+```
 
-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.
+And make sure you are using `rack-session` version `2.1.0` or later.
 
-Tidewave will raise an error if it is used in any environment where code reloading is disabled (which typically includes production).
+The above will allow your application to run embedded within Tidewave across multiple subdomains, as long as it is using a secure context (such as `admin.localhost`, `www.foobar.localhost`, etc).
 
-### Localhost requirement
+### Content security policy
 
-> This requirement only matters if you are not using the Tidewave app/CLI.
+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.
 
-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`:
+### Production Environment
 
-```ruby
-config.hosts << "company.local"
-config.tidewave.allow_remote_access = true
-```
+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.
 
-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 [containers](https://hexdocs.pm/tidewave/containers.html) guide for more information.
+Tidewave will raise an error if it is used in any environment where code reloading is disabled (which typically includes production).
 
 ## Configuration
 
@@ -49,7 +66,7 @@ You may configure `tidewave` using the following syntax:
 
 The following config is available:
 
-  * `allow_remote_access` - Tidewave only allows requests from localhost by default, even if your server listens on other interfaces. If you trust your network and need to access Tidewave from a different machine, this configuration can be set to `true`
+  * `allow_remote_access` - Tidewave only allows requests from localhost by default, even if your server listens on other interfaces, for security purposes. Read [our security guidelines for more information and when to allow remote access](https://hexdocs.pm/tidewave/security.html) (if you know what you are doing)
 
   * `logger_middleware` - The logger middleware Tidewave should wrap to silence its own logs
 
@@ -57,9 +74,29 @@ The following config is available:
 
   * `team` - set your Tidewave Team configuration, such as `config.tidewave.team = { id: "my-company" }`
 
+## Available tools
+
+- `execute_sql_query` - executes a SQL query within your application
+  database, useful for the agent to verify the result of an action
+
+- `get_docs` - get the documentation for a given module/class/method.
+  It consults the exact versions used by the project, ensuring you always
+  get correct information
+
+- `get_logs` - reads logs written by the server
+
+- `get_models` - lists all modules in the application and their location
+  for quick discovery
+
+- `get_source_location` - get the source location for a given module/class/method,
+  so an agent can directly read the source skipping search
+
+- `project_eval` - evaluates code within the Rails application itself, giving the agent
+  access to your runtime, dependencies, and in-memory data
+
 ## Acknowledgements
 
-A thank you to Yorick Jacquin, for creating [FastMCP](https://github.com/yjacquin/fast_mcp) and implementing the initial version of this project.
+A thank you to Yorick Jacquin for the initial version of this project.
 
 ## License
 

data/lib/tidewave/configuration.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
-module Tidewave
+class Tidewave
   class Configuration
     attr_accessor :logger, :allow_remote_access, :preferred_orm, :dev, :client_url, :team, :logger_middleware
 
     def initialize
-      @logger = nil
+      # Rails has a hosts middleware which already checks for this
       @allow_remote_access = true
+      @logger = nil
       @preferred_orm = :active_record
       @dev = false
       @client_url = "https://tidewave.ai"

data/lib/tidewave/database_adapter.rb

@@ -1,14 +1,9 @@
 # frozen_string_literal: true
 
-module Tidewave
+class Tidewave
   class DatabaseAdapter
     class << self
-      def current
-        @current ||= create_adapter
-      end
-
-      def create_adapter
-        orm_type = Rails.application.config.tidewave.preferred_orm
+      def for(orm_type)
         case orm_type
         when :active_record
           require_relative "database_adapters/active_record"

data/lib/tidewave/database_adapters/active_record.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Tidewave
+class Tidewave
   module DatabaseAdapters
     class ActiveRecord < DatabaseAdapter
       RESULT_LIMIT = 50
@@ -21,19 +21,13 @@ module Tidewave
           rows: result.rows.first(RESULT_LIMIT),
           row_count: result.rows.length,
           adapter: conn.adapter_name,
-          database: database_name
+          database: conn.pool.db_config.database
         }
       end
 
       def get_models
         ::ActiveRecord::Base.descendants
       end
-
-      private
-
-      def database_name
-        Rails.configuration.database_configuration.dig(Rails.env, "database")
-      end
     end
   end
 end

data/lib/tidewave/database_adapters/sequel.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Tidewave
+class Tidewave
   module DatabaseAdapters
     class Sequel < DatabaseAdapter
       RESULT_LIMIT = 50
@@ -31,7 +31,19 @@ module Tidewave
 
       def get_models
         # Filter out anonymous Sequel models that can't be resolved as constants
-        ::Sequel::Model.descendants.reject { |model| model.name&.start_with?("Sequel::_Model(") }
+        descendants_of(::Sequel::Model).reject { |model| model.name&.start_with?("Sequel::_Model(") }
+      end
+
+      private
+
+      def descendants_of(base)
+        if base.respond_to?(:descendants)
+          base.descendants
+        elsif base.respond_to?(:subclasses)
+          base.subclasses.flat_map { |subclass| [ subclass ] + descendants_of(subclass) }
+        else
+          []
+        end
       end
     end
   end

data/lib/tidewave/railtie.rb

@@ -1,37 +1,11 @@
 # frozen_string_literal: true
 
 require "logger"
-require "fileutils"
 require "tidewave/configuration"
-require "tidewave/middleware"
 require "tidewave/exceptions_middleware"
 require "tidewave/quiet_requests_middleware"
 
-gem_tools_path = File.expand_path("tools/**/*.rb", __dir__)
-Dir[gem_tools_path].each { |f| require f }
-
-# Temporary monkey patching to address regression in FastMCP
-if Dry::Schema::Macros::Hash.method_defined?(:original_call)
-  Dry::Schema::Macros::Hash.class_eval do
-    def call(*args, &block)
-      if block
-        # Use current context to track nested context if available
-        context = MetadataContext.current
-        if context
-          context.with_nested(name) do
-            original_call(*args, &block)
-          end
-        else
-          original_call(*args, &block)
-        end
-      else
-        original_call(*args)
-      end
-    end
-  end
-end
-
-module Tidewave
+class Tidewave
   class Railtie < Rails::Railtie
     config.tidewave = Tidewave::Configuration.new()
 
@@ -40,10 +14,21 @@ module Tidewave
         raise "For security reasons, Tidewave is only supported in environments where config.enable_reloading is true (typically development)"
       end
 
+      tidewave_config = app.config.tidewave
+
       app.config.middleware.insert_after(
         ActionDispatch::Callbacks,
-        Tidewave::Middleware,
-        app.config.tidewave
+        Tidewave,
+        allow_remote_access: tidewave_config.allow_remote_access,
+        client_url: tidewave_config.client_url,
+        framework_type: "rails",
+        project_name: app.class.module_parent.name,
+        team: tidewave_config.team,
+        logger: tidewave_config.logger || Rails.logger,
+        root: Rails.root,
+        log_file: Rails.root.join("log", "#{Rails.env}.log"),
+        orm_adapter: tidewave_config.preferred_orm,
+        before_reload: -> { app.eager_load! }
       )
 
       app.config.after_initialize do

data/lib/tidewave/tool.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+class Tidewave
+  class Tool
+    class << self
+      def descendants
+        @descendants ||= []
+      end
+
+      def inherited(subclass)
+        descendants << subclass
+        super
+      end
+    end
+
+    def initialize(_options = {})
+    end
+
+    def definition
+      raise NotImplementedError, "#{self.class} must implement #definition"
+    end
+
+    def call(_arguments = {})
+      raise NotImplementedError, "#{self.class} must implement #call"
+    end
+
+    def validate_and_call(arguments)
+      arguments ||= {}
+
+      unless arguments.is_a?(Hash)
+        raise ArgumentError, "Invalid arguments: expected an object"
+      end
+
+      # This validator intentionally enforces only a small subset of JSON Schema:
+      # `type`, `required`, and scalar `default` values. Other keywords such as
+      # `minLength`, `maxLength`, `enum`, and `pattern` remain descriptive until
+      # Tidewave grows broader schema support.
+      validate_schema(arguments, definition.fetch("inputSchema", {}))
+      call(arguments)
+    end
+
+    private
+
+    def validate_schema(value, schema, path = nil)
+      return unless schema.is_a?(Hash)
+
+      validate_type(value, schema["type"], path) if schema["type"]
+
+      case schema["type"]
+      when "object"
+        validate_object(value, schema, path)
+      when "array"
+        validate_array(value, schema, path)
+      end
+    end
+
+    def validate_object(value, schema, path)
+      properties = schema.fetch("properties", {})
+
+      properties.each do |name, property_schema|
+        if !value.key?(name) && property_schema.is_a?(Hash) && property_schema.key?("default")
+          validate_default(property_schema["default"], property_path(path, name))
+          value[name] = property_schema["default"]
+        end
+
+        next unless value.key?(name)
+
+        validate_schema(value[name], property_schema, property_path(path, name))
+      end
+
+      validate_required_properties(value, schema.fetch("required", []), path)
+    end
+
+    def validate_array(value, schema, path)
+      item_schema = schema["items"]
+      return unless item_schema.is_a?(Hash) && !item_schema.empty?
+
+      value.each_with_index do |item, index|
+        validate_schema(item, item_schema, "#{path || 'value'}[#{index}]")
+      end
+    end
+
+    def validate_required_properties(value, required_properties, path)
+      required_properties.each do |name|
+        next if value.key?(name)
+
+        raise ArgumentError, "Invalid arguments: missing required property '#{property_path(path, name)}'"
+      end
+    end
+
+    def validate_type(value, type, path)
+      return if value_matches_type?(value, type)
+
+      raise ArgumentError, "Invalid arguments: property '#{path || 'value'}' must be #{article_for(type)} #{type}"
+    end
+
+    def value_matches_type?(value, type)
+      case type
+      when "object"
+        value.is_a?(Hash)
+      when "array"
+        value.is_a?(Array)
+      when "string"
+        value.is_a?(String)
+      when "integer"
+        value.is_a?(Integer)
+      when "boolean"
+        value == true || value == false
+      else
+        true
+      end
+    end
+
+    def property_path(path, name)
+      path ? "#{path}.#{name}" : name
+    end
+
+    def article_for(type)
+      %w[array integer object].include?(type) ? "an" : "a"
+    end
+
+    def validate_default(value, path)
+      return unless value.is_a?(Hash) || value.is_a?(Array)
+
+      raise ArgumentError, "Invalid tool definition: property '#{path}' cannot use an object or array default"
+    end
+  end
+end

data/lib/tidewave/tools/execute_sql_query.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-class Tidewave::Tools::ExecuteSqlQuery < Tidewave::Tools::Base
-  tool_name "execute_sql_query"
-  description <<~DESCRIPTION
+class Tidewave::Tools::ExecuteSqlQuery < Tidewave::Tool
+  DESCRIPTION = <<~DESCRIPTION.freeze
     Executes the given SQL query against the database connection.
     Returns the result as a Ruby data structure.
 
@@ -17,20 +16,38 @@ class Tidewave::Tools::ExecuteSqlQuery < Tidewave::Tools::Base
     For MySQL, use ? for parameter placeholders.
   DESCRIPTION
 
-  arguments do
-    required(:query).filled(:string).description("The SQL query to execute. For PostgreSQL, use $1, $2 placeholders. For MySQL, use ? placeholders.")
-    optional(:arguments).value(:array).description("The arguments to pass to the query. The query must contain corresponding parameter placeholders.")
+  def initialize(options = {})
+    @database_adapter = Tidewave::DatabaseAdapter.for(options[:orm_adapter]) if options[:orm_adapter]
   end
 
-  def @input_schema.json_schema
-    schema = super
-    schema[:properties][:arguments][:items] = {}
-    schema
+  def definition
+    return nil unless @database_adapter
+
+    {
+      "name" => "execute_sql_query",
+      "description" => DESCRIPTION,
+      "inputSchema" => {
+        "type" => "object",
+        "properties" => {
+          "query" => {
+            "type" => "string",
+            "minLength" => 1,
+            "description" => "The SQL query to execute. For PostgreSQL, use $1, $2 placeholders. For MySQL, use ? placeholders."
+          },
+          "arguments" => {
+            "type" => "array",
+            "items" => {},
+            "description" => "The arguments to pass to the query. The query must contain corresponding parameter placeholders."
+          }
+        },
+        "required" => [ "query" ]
+      }
+    }
   end
 
-  RESULT_LIMIT = 50
-
-  def call(query:, arguments: [])
-    Tidewave::DatabaseAdapter.current.execute_query(query, arguments)
+  def call(arguments_hash)
+    query = arguments_hash.fetch("query")
+    arguments = arguments_hash.fetch("arguments", [])
+    @database_adapter.execute_query(query, arguments)
   end
 end

data/lib/tidewave/tools/get_docs.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 
-class Tidewave::Tools::GetDocs < Tidewave::Tools::Base
-  tool_name "get_docs"
-
-  description <<~DESCRIPTION
+class Tidewave::Tools::GetDocs < Tidewave::Tool
+  DESCRIPTION = <<~DESCRIPTION.freeze
     Returns the documentation for the given reference.
 
     The reference may be a constant, most commonly classes and modules
@@ -16,11 +14,26 @@ class Tidewave::Tools::GetDocs < Tidewave::Tools::Base
     If that is the case, prefer this tool over grepping the file system.
   DESCRIPTION
 
-  arguments do
-    required(:reference).filled(:string).description("The constant/method to lookup, such String, String#gsub or File.executable?")
+  def definition
+    {
+      "name" => "get_docs",
+      "description" => DESCRIPTION,
+      "inputSchema" => {
+        "type" => "object",
+        "properties" => {
+          "reference" => {
+            "type" => "string",
+            "minLength" => 1,
+            "description" => "The constant/method to lookup, such String, String#gsub or File.executable?"
+          }
+        },
+        "required" => [ "reference" ]
+      }
+    }
   end
 
-  def call(reference:)
+  def call(arguments)
+    reference = arguments.fetch("reference")
     file_path, line_number = Tidewave::Tools::GetSourceLocation.get_source_location(reference)
 
     if file_path
@@ -47,7 +60,8 @@ class Tidewave::Tools::GetDocs < Tidewave::Tools::Base
       line = lines[current_line].chomp.strip
 
       if line.start_with?("#")
-        comment_lines.unshift(line.sub(/^#\s|^#/, ""))
+        comment = line.sub(/^#\s|^#/, "")
+        comment_lines.unshift(comment) unless ignorable_comment?(comment)
       elsif line.empty?
         # Skip empty lines but continue looking for comments
       else
@@ -61,4 +75,8 @@ class Tidewave::Tools::GetDocs < Tidewave::Tools::Base
     return nil if comment_lines.empty?
     comment_lines.join("\n")
   end
+
+  def ignorable_comment?(comment)
+    comment.start_with?("rubocop:")
+  end
 end

data/lib/tidewave/tools/get_logs.rb

@@ -1,26 +1,54 @@
 # frozen_string_literal: true
 
-class Tidewave::Tools::GetLogs < Tidewave::Tools::Base
-  tool_name "get_logs"
-  description <<~DESCRIPTION
+require "pathname"
+
+class Tidewave::Tools::GetLogs < Tidewave::Tool
+  DESCRIPTION = <<~DESCRIPTION.freeze
     Returns all log output, excluding logs that were caused by other tool calls.
 
     Use this tool to check for request logs or potentially logged errors.
   DESCRIPTION
 
-  arguments do
-    required(:tail).filled(:integer).description("The number of log entries to return from the end of the log")
-    optional(:grep).filled(:string).description("Filter logs with the given regular expression (case insensitive). E.g. \"error\" when you want to capture errors in particular")
+  def initialize(options = {})
+    @log_file = options[:log_file] ? Pathname.new(options[:log_file].to_s) : nil
+  end
+
+  def definition
+    return nil unless @log_file
+
+    {
+      "name" => "get_logs",
+      "description" => DESCRIPTION,
+      "inputSchema" => {
+        "type" => "object",
+        "properties" => {
+          "tail" => {
+            "type" => "integer",
+            "not" => {
+              "type" => "null"
+            },
+            "description" => "The number of log entries to return from the end of the log"
+          },
+          "grep" => {
+            "type" => "string",
+            "minLength" => 1,
+            "description" => "Filter logs with the given regular expression (case insensitive). E.g. \"error\" when you want to capture errors in particular"
+          }
+        },
+        "required" => [ "tail" ]
+      }
+    }
   end
 
-  def call(tail:, grep: nil)
-    log_file = Rails.root.join("log", "#{Rails.env}.log")
-    return "Log file not found" unless File.exist?(log_file)
+  def call(arguments)
+    tail = arguments.fetch("tail")
+    grep = arguments["grep"]
+    return "Log file not found" unless @log_file&.exist?
 
     regex = Regexp.new(grep, Regexp::IGNORECASE) if grep
     matching_lines = []
 
-    tail_lines(log_file) do |line|
+    tail_lines(@log_file) do |line|
       if regex.nil? || line.match?(regex)
         matching_lines.unshift(line)
         break if matching_lines.size >= tail