rails-hyperdrive 0.3.0

data/lib/rails/hyperdrive/tools/locate_source.rb

@@ -0,0 +1,86 @@
+require_relative "base"
+
+module Rails
+  module Hyperdrive
+    module Tools
+      class LocateSource < Base
+        tool_name "locate_source"
+        description "Resolve a reference to file:line. Accepts 'Const#instance_method', 'Const.class_method', 'Const' (constant location), or 'dep:<gem>' (gem path)."
+
+        input_schema(
+          properties: {
+            reference: { type: "string", description: "Reference to locate." }
+          },
+          required: ["reference"]
+        )
+
+        def self.call(reference:, server_context: nil)
+          with_dev_guard do
+            resolve(reference.to_s.strip)
+          end
+        end
+
+        def self.resolve(reference)
+          if reference.start_with?("dep:")
+            return resolve_gem(reference.sub(/\Adep:/, ""), reference)
+          end
+
+          if reference.include?("#")
+            klass_name, method = reference.split("#", 2)
+            klass = constantize(klass_name)
+            unless instance_method_defined?(klass, method)
+              return respond_error("could not resolve: #{reference}")
+            end
+            file, line = klass.instance_method(method.to_sym).source_location
+            file ? respond_text("#{file}:#{line}") : respond_error("could not resolve: #{reference}")
+          elsif reference.include?(".")
+            klass_name, method = reference.split(".", 2)
+            klass = constantize(klass_name)
+            unless klass.respond_to?(method, true)
+              return respond_error("could not resolve: #{reference}")
+            end
+            file, line = klass.method(method.to_sym).source_location
+            file ? respond_text("#{file}:#{line}") : respond_error("could not resolve: #{reference}")
+          else
+            owner_name, const_name = split_const(reference)
+            owner = constantize(owner_name)
+            return respond_error("could not resolve: #{reference}") unless owner.respond_to?(:const_source_location)
+            location = owner.const_source_location(const_name)
+            location && location.first ? respond_text("#{location[0]}:#{location[1]}") : respond_error("could not resolve: #{reference}")
+          end
+        rescue NameError
+          respond_error("could not resolve: #{reference}")
+        end
+
+        def self.split_const(reference)
+          if reference.include?("::")
+            parts = reference.split("::")
+            [parts[0..-2].join("::"), parts.last]
+          else
+            ["Object", reference]
+          end
+        end
+
+        def self.instance_method_defined?(klass, method)
+          sym = method.to_sym
+          klass.instance_methods(true).include?(sym) ||
+            klass.private_instance_methods(true).include?(sym)
+        end
+
+        def self.resolve_gem(name, reference)
+          spec = Gem::Specification.find_all_by_name(name).first
+          return respond_error("could not resolve: #{reference}") unless spec
+          respond_text(spec.full_gem_path)
+        end
+
+        def self.constantize(name)
+          if defined?(::ActiveSupport) && String.method_defined?(:constantize)
+            name.constantize
+          else
+            name.split("::").inject(Object) { |m, c| m.const_get(c) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/tools/lookup_doc.rb

@@ -0,0 +1,60 @@
+require "open3"
+require "timeout"
+require_relative "base"
+
+module Rails
+  module Hyperdrive
+    module Tools
+      class LookupDoc < Base
+        tool_name "lookup_doc"
+        description "Look up documentation for a Ruby/Rails symbol via `ri`. Returns markdown text."
+
+        RI_TIMEOUT_SECONDS = 10
+
+        input_schema(
+          properties: {
+            reference: { type: "string", description: "Symbol to document (e.g. 'String#strip', 'ActiveRecord::Base.find')." }
+          },
+          required: ["reference"]
+        )
+
+        def self.call(reference:, server_context: nil)
+          with_dev_guard do
+            ref = reference.to_s.strip
+            stdout, stderr, status = run_ri(ref)
+            return respond_error("ri not available") if status.nil?
+            return respond_text(stdout) if status.success?
+            first_stderr_line = stderr.to_s.lines.first.to_s.strip
+            respond_error("ri exited #{status.exitstatus}: #{first_stderr_line}")
+          end
+        end
+
+        # The manual timeout lets a hung ri be TERMed; a missing ri returns
+        # [nil, nil, nil].
+        def self.run_ri(reference)
+          Open3.popen3("ri", "-T", "--format=markdown", reference) do |_in, out, err, wait_thr|
+            begin
+              ::Timeout.timeout(RI_TIMEOUT_SECONDS) do
+                stdout = out.read
+                stderr = err.read
+                [stdout, stderr, wait_thr.value]
+              end
+            rescue ::Timeout::Error
+              begin
+                Process.kill("TERM", wait_thr.pid)
+              rescue Errno::ESRCH
+              end
+              ["", "ri timeout after #{RI_TIMEOUT_SECONDS}s", FakeStatus.new(124)]
+            end
+          end
+        rescue Errno::ENOENT
+          [nil, nil, nil]
+        end
+
+        FakeStatus = Struct.new(:exitstatus) do
+          def success?; false; end
+        end
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/tools/run_ruby.rb

@@ -0,0 +1,31 @@
+require_relative "base"
+require_relative "../console_executor"
+
+module Rails
+  module Hyperdrive
+    module Tools
+      class RunRuby < Base
+        tool_name "run_ruby"
+        description "Eval Ruby in the booted Rails process with timeout and stdout/stderr capture. Returns { result, stdout, stderr, elapsed_ms, exception }."
+
+        MAX_TIMEOUT_SECONDS = 120
+
+        input_schema(
+          properties: {
+            code: { type: "string", description: "Ruby source to eval at TOPLEVEL_BINDING." },
+            timeout: { type: "integer", description: "Timeout in seconds (default 30, max 120)." }
+          },
+          required: ["code"]
+        )
+
+        def self.call(code:, timeout: Rails::Hyperdrive::ConsoleExecutor::DEFAULT_TIMEOUT_SECONDS, server_context: nil)
+          with_dev_guard do
+            t = [[timeout.to_i, 1].max, MAX_TIMEOUT_SECONDS].min
+            result = Rails::Hyperdrive::ConsoleExecutor.eval(code, timeout: t)
+            respond_json(result.to_h)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/tools/run_sql.rb

@@ -0,0 +1,49 @@
+require_relative "base"
+require_relative "../sql_safety"
+
+module Rails
+  module Hyperdrive
+    module Tools
+      class RunSql < Base
+        tool_name "run_sql"
+        description "Read-only SQL via ActiveRecord::Base.connection. Rejects INSERT/UPDATE/DELETE/DROP/etc. at the parser level. Caps results at 100 rows."
+
+        ROW_CAP = 100
+
+        input_schema(
+          properties: {
+            sql: { type: "string", description: "A SELECT / WITH / EXPLAIN / SHOW / PRAGMA statement." }
+          },
+          required: ["sql"]
+        )
+
+        def self.call(sql:, server_context: nil)
+          with_dev_guard do
+            begin
+              Rails::Hyperdrive::SqlSafety.assert_read_only!(sql)
+            rescue Rails::Hyperdrive::SqlSafety::Error => e
+              return respond_error("SQL not allowed: #{e.message}")
+            end
+
+            begin
+              result = ActiveRecord::Base.connection.exec_query(sql)
+            rescue ActiveRecord::ActiveRecordError => e
+              return respond_error("#{e.class}: #{e.message}")
+            end
+
+            respond_text(format_table(result))
+          end
+        end
+
+        def self.format_table(result)
+          rows = result.rows
+          shown = rows.first(ROW_CAP)
+          lines = [result.columns.join("\t")]
+          shown.each { |row| lines << row.map { |v| v.to_s }.join("\t") }
+          lines << "(#{rows.length} rows, truncated)" if rows.length > ROW_CAP
+          lines.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/tools/tail_logs.rb

@@ -0,0 +1,65 @@
+require_relative "base"
+
+module Rails
+  module Hyperdrive
+    module Tools
+      class TailLogs < Base
+        tool_name "tail_logs"
+        description "Return the last N lines of a log file under Rails.root/log/. Defaults to <env>.log."
+
+        DEFAULT_LINES = 200
+        MAX_LINES = 2_000
+
+        input_schema(
+          properties: {
+            lines: { type: "integer", description: "Number of trailing lines (default 200, max 2000)." },
+            file:  { type: "string",  description: "Log file path. Default: log/<Rails.env>.log. Must resolve inside Rails.root/log/." }
+          }
+        )
+
+        def self.call(lines: DEFAULT_LINES, file: nil, server_context: nil)
+          with_dev_guard do
+            n = [[lines.to_i, 1].max, MAX_LINES].min
+            log_dir = ::Rails.root.join("log").expand_path
+            requested = file.to_s.empty? ? "#{::Rails.env}.log" : file.to_s
+            log_path = resolve_path(log_dir, requested)
+            return respond_error("log not allowed: path escapes Rails.root/log/") unless log_path
+            return respond_error("log not found: #{log_path}") unless File.exist?(log_path)
+            respond_text(tail(log_path, n))
+          end
+        end
+
+        # Path-traversal guard: the resolved target must stay inside log_dir.
+        def self.resolve_path(log_dir, requested)
+          base = Pathname.new(requested)
+          target = base.absolute? ? base : (log_dir + base)
+          target = Pathname.new(File.expand_path(target.to_s))
+          return nil unless target.to_s == log_dir.to_s || target.to_s.start_with?(log_dir.to_s + File::SEPARATOR)
+          target
+        end
+
+        # Pure-Ruby `tail -n` — portable and avoids shell-escaping risk.
+        def self.tail(path, lines)
+          block_size = 8 * 1024
+          File.open(path, "rb") do |f|
+            f.seek(0, IO::SEEK_END)
+            file_size = f.pos
+            buffer = +""
+            newline_count = 0
+            while f.pos > 0 && newline_count <= lines
+              read_size = [block_size, f.pos].min
+              f.seek(-read_size, IO::SEEK_CUR)
+              chunk = f.read(read_size)
+              f.seek(-read_size, IO::SEEK_CUR)
+              buffer.prepend(chunk)
+              newline_count = buffer.count("\n")
+            end
+            buffer.force_encoding(Encoding.default_external).scrub
+            last = buffer.lines.last(lines).join
+            last.empty? && file_size > 0 ? buffer : last
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/version.rb

@@ -0,0 +1,5 @@
+module Rails
+  module Hyperdrive
+    VERSION = "0.3.0"
+  end
+end

data/lib/rails/hyperdrive.rb

@@ -0,0 +1,37 @@
+require "rails/hyperdrive/version"
+
+module Rails
+  module Hyperdrive
+    class Configuration
+      DEFAULT_MOUNT_AT = "/_hyperdrive".freeze
+
+      attr_accessor :mount_at
+
+      def initialize
+        @mount_at = DEFAULT_MOUNT_AT
+      end
+    end
+
+    def self.root
+      @root ||= File.expand_path("..", __dir__)
+    end
+
+    def self.dev_mode?
+      defined?(::Rails) && ::Rails.respond_to?(:env) && ::Rails.env.development?
+    end
+
+    def self.configuration
+      @configuration ||= Configuration.new
+    end
+
+    def self.configure
+      yield(configuration)
+    end
+
+    def self.reset_configuration!
+      @configuration = nil
+    end
+  end
+end
+
+require "rails/hyperdrive/engine" if defined?(::Rails::Engine)

data/lib/rails-hyperdrive.rb

@@ -0,0 +1,2 @@
+# Bundler auto-requires this gem by its dashed name ("rails-hyperdrive").
+require "rails/hyperdrive"

data/lib/tasks/hyperdrive.rake

@@ -0,0 +1,22 @@
+namespace :hyperdrive do
+  desc "Install Rails Hyperdrive into this app (writes .mcp.json, CLAUDE.md, skills, guidelines, mounts engine)"
+  task :init do
+    require "rails/generators"
+    require "generators/hyperdrive/install/install_generator"
+    Rails::Generators::Hyperdrive::InstallGenerator.start(ARGV.drop(1))
+  end
+
+  desc "Sync Rails Hyperdrive content (skills, guidelines, index.md, lockfile); locally-edited files are preserved — pass --overwrite to restore gem-shipped content"
+  task :sync do
+    require "rails/generators"
+    require "generators/hyperdrive/sync/sync_generator"
+    Rails::Generators::Hyperdrive::SyncGenerator.start(ARGV.drop(1))
+  end
+
+  desc "Suggest uninstalled rails-hyperdrive companion gems for this app's stack (networked, cached; pass --refresh to re-query)"
+  task :discover do
+    require "rails/generators"
+    require "generators/hyperdrive/discover/discover_generator"
+    Rails::Generators::Hyperdrive::DiscoverGenerator.start(ARGV.drop(1))
+  end
+end

metadata

@@ -0,0 +1,161 @@
+--- !ruby/object:Gem::Specification
+name: rails-hyperdrive
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Bakaface
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.25'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.25'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+description: |
+  Rails Hyperdrive mounts an MCP (Model Context Protocol) server at /_hyperdrive/mcp in development,
+  exposing introspection tools for AI coding agents (eval Ruby, query DB, tail logs,
+  list models/routes, locate source, fetch docs, snapshot stack). It also ships a
+  `hyperdrive:init` generator that discovers and installs two artifact types — lazy skills
+  and eager guidelines — shipped by companion gems under a documented contract.
+  rails-hyperdrive is the mechanism; companion gems (rails-hyperdrive-<library>) are the content.
+email:
+- afaceisnomore@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- SECURITY.md
+- config/routes.rb
+- lib/generators/hyperdrive/content_sync_support.rb
+- lib/generators/hyperdrive/discover/discover_generator.rb
+- lib/generators/hyperdrive/gitignore_support.rb
+- lib/generators/hyperdrive/install/USAGE
+- lib/generators/hyperdrive/install/install_generator.rb
+- lib/generators/hyperdrive/install/templates/initializer.rb.tt
+- lib/generators/hyperdrive/install_summary.rb
+- lib/generators/hyperdrive/sync/USAGE
+- lib/generators/hyperdrive/sync/sync_generator.rb
+- lib/generators/hyperdrive/sync_runner.rb
+- lib/rails-hyperdrive.rb
+- lib/rails/hyperdrive.rb
+- lib/rails/hyperdrive/artifact_status.rb
+- lib/rails/hyperdrive/audit_header.rb
+- lib/rails/hyperdrive/auto_install.rb
+- lib/rails/hyperdrive/bundler_artifact_discovery.rb
+- lib/rails/hyperdrive/claude_md_import.rb
+- lib/rails/hyperdrive/companion_discovery.rb
+- lib/rails/hyperdrive/console_executor.rb
+- lib/rails/hyperdrive/data/gem_categories.yml
+- lib/rails/hyperdrive/drift_verdict.rb
+- lib/rails/hyperdrive/eager_footprint.rb
+- lib/rails/hyperdrive/engine.rb
+- lib/rails/hyperdrive/index_document.rb
+- lib/rails/hyperdrive/install_layout.rb
+- lib/rails/hyperdrive/install_pipeline.rb
+- lib/rails/hyperdrive/install_plan.rb
+- lib/rails/hyperdrive/install_shell.rb
+- lib/rails/hyperdrive/lock_file.rb
+- lib/rails/hyperdrive/mcp_server.rb
+- lib/rails/hyperdrive/resources/skill.rb
+- lib/rails/hyperdrive/resources/stack_profile.rb
+- lib/rails/hyperdrive/safety/rack_middleware.rb
+- lib/rails/hyperdrive/skill_template.rb
+- lib/rails/hyperdrive/sql_safety.rb
+- lib/rails/hyperdrive/stack_profile.rb
+- lib/rails/hyperdrive/tools/base.rb
+- lib/rails/hyperdrive/tools/describe_app.rb
+- lib/rails/hyperdrive/tools/list_models.rb
+- lib/rails/hyperdrive/tools/list_routes.rb
+- lib/rails/hyperdrive/tools/locate_source.rb
+- lib/rails/hyperdrive/tools/lookup_doc.rb
+- lib/rails/hyperdrive/tools/run_ruby.rb
+- lib/rails/hyperdrive/tools/run_sql.rb
+- lib/rails/hyperdrive/tools/tail_logs.rb
+- lib/rails/hyperdrive/version.rb
+- lib/tasks/hyperdrive.rake
+homepage: https://github.com/rails-hyperdrive/rails-hyperdrive
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rails-hyperdrive/rails-hyperdrive
+  source_code_uri: https://github.com/rails-hyperdrive/rails-hyperdrive
+  changelog_uri: https://github.com/rails-hyperdrive/rails-hyperdrive/blob/main/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Dev-only Rails engine that bootstraps an MCP server + skills/guidelines for
+  AI coding agents.
+test_files: []