rails-hyperdrive 0.3.0

data/lib/rails/hyperdrive/companion_discovery.rb

@@ -0,0 +1,232 @@
+require "json"
+require "net/http"
+require "openssl"
+require "timeout"
+require "uri"
+require "time"
+require "fileutils"
+require "bundler"
+
+module Rails
+  module Hyperdrive
+    class CompanionDiscovery
+      TARGETS_KEY         = "rails_hyperdrive_targets".freeze
+      ARTIFACTS_KEY       = "rails_hyperdrive_artifacts".freeze
+      # Field-scoped metadata search is an undocumented passthrough to the
+      # rubygems search backend, so it fails open: if it ever stops matching, the
+      # query returns an empty 200 page and discovery reports no suggestions.
+      SEARCH_QUERY        = "metadata.#{TARGETS_KEY}:*".freeze
+      SEARCH_ENDPOINT     = "https://rubygems.org/api/v1/search.json".freeze
+      CACHE_RELATIVE_PATH = ".hyperdrive/discover_cache.json".freeze
+      PER_PAGE            = 30
+      MAX_PAGES           = 34 # ~1000 companions; a runaway-pagination backstop
+      CACHE_TTL           = 24 * 60 * 60
+      OPEN_TIMEOUT        = 5
+      READ_TIMEOUT        = 5
+
+      # matched_target is nil for a universal "*" companion.
+      Suggestion = Struct.new(
+        :gem_name, :version, :targets, :artifacts,
+        :matched_target, :matched_version, :installed,
+        keyword_init: true
+      )
+
+      # Outcome of a run.
+      #   status: :online      — served live or fresh-cached results
+      #           :stale       — network failed; served an expired cache
+      #           :unavailable — network failed and no cache to fall back to
+      Result = Struct.new(:suggestions, :warnings, :status, :age_seconds, :detail, keyword_init: true)
+
+      class Unavailable < StandardError
+        attr_reader :retry_after
+
+        def initialize(message, retry_after: nil)
+          super(message)
+          @retry_after = retry_after
+        end
+      end
+
+      Response = Struct.new(:code, :body, :retry_after, keyword_init: true)
+
+      class NetHttpFetcher
+        def get(uri)
+          uri = URI(uri)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+          http.open_timeout = OPEN_TIMEOUT
+          http.read_timeout = READ_TIMEOUT
+          resp = http.get(uri.request_uri)
+          Response.new(code: resp.code.to_i, body: resp.body.to_s, retry_after: resp["retry-after"])
+        end
+      end
+
+      def initialize(lockfile_path:, cache_path:, refresh: false, fetcher: NetHttpFetcher.new, clock: -> { Time.now.utc })
+        @lockfile_path = lockfile_path.to_s
+        @cache_path    = cache_path.to_s
+        @refresh       = refresh
+        @fetcher       = fetcher
+        @clock         = clock
+      end
+
+      def run
+        warnings = []
+        now = @clock.call
+        candidates, status, age, detail = resolve_candidates(now)
+
+        return Result.new(suggestions: [], warnings: warnings, status: :unavailable, detail: detail) if status == :unavailable
+
+        suggestions = match(candidates, warnings)
+        Result.new(suggestions: suggestions, warnings: warnings, status: status, age_seconds: age, detail: detail)
+      end
+
+      private
+
+      def resolve_candidates(now)
+        cache = read_cache
+        if !@refresh && cache && fresh?(cache, now)
+          return [cache[:candidates], :online, age_of(cache, now), nil]
+        end
+
+        begin
+          candidates = fetch_all
+          write_cache(candidates, now)
+          [candidates, :online, 0, nil]
+        rescue Unavailable => e
+          detail = unavailable_detail(e)
+          if cache
+            [cache[:candidates], :stale, age_of(cache, now), detail]
+          else
+            [[], :unavailable, nil, detail]
+          end
+        end
+      end
+
+      def unavailable_detail(error)
+        if error.retry_after
+          "rubygems rate-limited the request (retry after #{error.retry_after}s)"
+        else
+          "rubygems unreachable (#{error.message})"
+        end
+      end
+
+      def fetch_all
+        candidates = []
+        page = 1
+        loop do
+          batch = fetch_page(page)
+          candidates.concat(batch)
+          break if batch.size < PER_PAGE
+          page += 1
+          break if page > MAX_PAGES
+        end
+        candidates
+      rescue SocketError, SystemCallError, Timeout::Error, OpenSSL::SSL::SSLError, IOError => e
+        raise Unavailable, e.message
+      end
+
+      def fetch_page(page)
+        uri = "#{SEARCH_ENDPOINT}?query=#{URI.encode_www_form_component(SEARCH_QUERY)}&page=#{page}"
+        resp = @fetcher.get(uri)
+
+        case resp.code
+        when 200
+          parse_search(resp.body)
+        when 429
+          raise Unavailable.new("rate limited", retry_after: resp.retry_after)
+        else
+          raise Unavailable, "HTTP #{resp.code}"
+        end
+      end
+
+      def parse_search(body)
+        data = JSON.parse(body)
+        return [] unless data.is_a?(Array)
+        data.map { |gem| { name: gem["name"].to_s, version: gem["version"].to_s, metadata: gem["metadata"] || {} } }
+      rescue JSON::ParserError => e
+        raise Unavailable, "malformed search response (#{e.message})"
+      end
+
+      def match(candidates, warnings)
+        installed = installed_gems
+        candidates.filter_map { |c| build_suggestion(c, installed, warnings) }
+                  .sort_by { |s| [s.installed ? 0 : 1, s.gem_name] }
+      end
+
+      def build_suggestion(candidate, installed, warnings)
+        name     = candidate[:name]
+        metadata = candidate[:metadata] || {}
+        targets  = parse_list(metadata[TARGETS_KEY])
+
+        if targets.empty?
+          warnings << "#{name} #{candidate[:version]}: no targets declared (skipped)"
+          return nil
+        end
+
+        matched_target, matched_version =
+          if targets.include?("*")
+            [nil, nil]
+          else
+            hit = targets.find { |t| installed.key?(t) }
+            return nil unless hit
+            [hit, installed[hit]]
+          end
+
+        Suggestion.new(
+          gem_name: name,
+          version: candidate[:version],
+          targets: targets,
+          artifacts: parse_list(metadata[ARTIFACTS_KEY]),
+          matched_target: matched_target,
+          matched_version: matched_version,
+          installed: installed.key?(name)
+        )
+      end
+
+      def parse_list(raw)
+        raw.to_s.split(",").map(&:strip).reject(&:empty?)
+      end
+
+      def installed_gems
+        return {} unless File.exist?(@lockfile_path)
+        parser = ::Bundler::LockfileParser.new(File.read(@lockfile_path))
+        parser.specs.each_with_object({}) { |s, h| h[s.name.to_s] = s.version.to_s }
+      rescue StandardError
+        # A malformed/unreadable lockfile must not break discovery — treat the
+        # stack as empty (only `*`-target companions will then match).
+        {}
+      end
+
+      def read_cache
+        return nil unless File.exist?(@cache_path)
+        data = JSON.parse(File.read(@cache_path))
+        fetched_at = Time.iso8601(data["fetched_at"].to_s)
+        candidates = Array(data["candidates"]).map do |c|
+          { name: c["name"].to_s, version: c["version"].to_s, metadata: c["metadata"] || {} }
+        end
+        { fetched_at: fetched_at, candidates: candidates }
+      rescue JSON::ParserError, ArgumentError, TypeError
+        nil
+      end
+
+      def write_cache(candidates, now)
+        FileUtils.mkdir_p(File.dirname(@cache_path))
+        payload = {
+          "fetched_at" => now.iso8601,
+          "candidates" => candidates.map { |c| { "name" => c[:name], "version" => c[:version], "metadata" => c[:metadata] } }
+        }
+        File.write(@cache_path, JSON.pretty_generate(payload) + "\n")
+      rescue SystemCallError
+        # A non-writable cache dir must not break discovery.
+        nil
+      end
+
+      def fresh?(cache, now)
+        age_of(cache, now) < CACHE_TTL
+      end
+
+      def age_of(cache, now)
+        now - cache[:fetched_at]
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/console_executor.rb

@@ -0,0 +1,64 @@
+require "stringio"
+require "timeout"
+
+module Rails
+  module Hyperdrive
+    module ConsoleExecutor
+      DEFAULT_TIMEOUT_SECONDS = 30
+
+      Result = Struct.new(:result, :stdout, :stderr, :elapsed_ms, :exception, keyword_init: true) do
+        def to_h
+          {
+            result: result.inspect,
+            stdout: stdout,
+            stderr: stderr,
+            elapsed_ms: elapsed_ms,
+            exception: exception && {
+              class: exception.class.name,
+              message: exception.message,
+              backtrace: Array(exception.backtrace).first(20)
+            }
+          }
+        end
+      end
+
+      module_function
+
+      def eval(code, timeout: DEFAULT_TIMEOUT_SECONDS)
+        original_stdout = $stdout
+        original_stderr = $stderr
+        captured_out = StringIO.new
+        captured_err = StringIO.new
+        $stdout = captured_out
+        $stderr = captured_err
+
+        started_at = monotonic_now
+        result = nil
+        exception = nil
+
+        begin
+          ::Timeout.timeout(timeout.to_f) do
+            result = TOPLEVEL_BINDING.eval(code, "(hyperdrive run_ruby)", 1)
+          end
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          exception = e
+        end
+
+        Result.new(
+          result: result,
+          stdout: captured_out.string,
+          stderr: captured_err.string,
+          elapsed_ms: ((monotonic_now - started_at) * 1000).round,
+          exception: exception
+        )
+      ensure
+        $stdout = original_stdout
+        $stderr = original_stderr
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/data/gem_categories.yml

@@ -0,0 +1,52 @@
+# Category assignment is reporting metadata only; nothing here is executed.
+
+test:
+  - rspec
+  - rspec-rails
+  - minitest
+  - minitest-rails
+  - test-unit
+  - capybara
+  - cucumber
+  - cucumber-rails
+
+jobs:
+  - sidekiq
+  - resque
+  - delayed_job
+  - good_job
+  - solid_queue
+  - sucker_punch
+  - shoryuken
+  - que
+
+auth:
+  - devise
+  - clearance
+  - sorcery
+  - authlogic
+  - rodauth
+  - rodauth-rails
+
+authz:
+  - pundit
+  - cancancan
+  - action_policy
+
+frontend:
+  - turbo-rails
+  - stimulus-rails
+  - importmap-rails
+  - jsbundling-rails
+  - cssbundling-rails
+  - view_component
+  - phlex
+  - phlex-rails
+  - hotwire-rails
+
+db:
+  - pg
+  - mysql2
+  - sqlite3
+  - trilogy
+  - sequel

data/lib/rails/hyperdrive/drift_verdict.rb

@@ -0,0 +1,42 @@
+require "digest"
+require "rails/hyperdrive/audit_header"
+
+module Rails
+  module Hyperdrive
+    # The lock's source_sha is computed over the install-ready body before any
+    # header injection, so hashing an installed file's comparable bytes
+    # (disk_sha) reproduces it exactly for an unedited file.
+    module DriftVerdict
+      STATES = %i[current outdated edited missing orphaned].freeze
+
+      module_function
+
+      # The install-ready body's hash — what the lock records as source_sha.
+      def body_sha(content)
+        Digest::SHA256.hexdigest(content.to_s)
+      end
+
+      # AuditHeader.strip's line matching can raise on binary content, so
+      # skill_support files compare as raw bytes.
+      def disk_sha(file, kind:)
+        return body_sha(File.binread(file)) if kind.to_s == "skill_support"
+        body_sha(AuditHeader.strip(File.read(file)))
+      end
+
+      # A file counts as unedited when its comparable bytes still hash to what
+      # the lock recorded at install time, not to what the gem ships now.
+      def unedited?(file, lock_entry:)
+        disk_sha(file, kind: lock_entry.kind) == lock_entry.source_sha
+      end
+
+      # gem_sha nil means the bundle no longer offers this destination.
+      def verdict(file:, kind:, lock_entry:, gem_sha:)
+        return File.exist?(file) ? :orphaned : :missing if gem_sha.nil?
+        return :missing unless File.exist?(file)
+        return :edited if lock_entry.nil?
+        return :edited if disk_sha(file, kind: kind) != lock_entry.source_sha
+        lock_entry.source_sha == gem_sha ? :current : :outdated
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/eager_footprint.rb

@@ -0,0 +1,48 @@
+require "rails/hyperdrive/install_layout"
+
+module Rails
+  module Hyperdrive
+    # Sizes the always-in-context set — the index-included guidelines — and
+    # returns the report as lines for a shell to print.
+    module EagerFootprint
+      # Soft cap on the assembled eager set — roughly six at-the-limit
+      # guidelines, or ~5% of a 200k context window.
+      TOTAL_WARN_TOKENS = 10_000
+
+      Line = Struct.new(:status, :message, :color, keyword_init: true)
+
+      module_function
+
+      def approx_tokens(body)
+        (body.to_s.length / 4.0).ceil
+      end
+
+      def lines(guidelines:)
+        return [] if guidelines.empty?
+
+        tokens = guidelines.sum { |e| approx_tokens(e[:body]) }
+
+        result = [Line.new(
+          status: :eager,
+          message: "#{guidelines.size} guideline(s), ~#{tokens} tokens always in context",
+          color: :cyan
+        )]
+        result << over_budget_line(guidelines) if tokens > TOTAL_WARN_TOKENS
+        result
+      end
+
+      def over_budget_line(entries)
+        top = entries.sort_by { |e| -approx_tokens(e[:body]) }.first(2)
+          .map { |e| "#{e[:name]} ~#{approx_tokens(e[:body])}" }
+        Line.new(
+          status: :warn,
+          message: "eager context is over the ~#{TOTAL_WARN_TOKENS} token budget (largest: #{top.join(", ")}); " \
+            "trim them, or drop a line from #{InstallLayout::INDEX_PATH} to opt one out",
+          color: :yellow
+        )
+      end
+
+      private_class_method :over_budget_line
+    end
+  end
+end

data/lib/rails/hyperdrive/engine.rb

@@ -0,0 +1,22 @@
+require "rails/engine"
+
+module Rails
+  module Hyperdrive
+    # Loads in every environment so an accidental non-dev bundle group doesn't
+    # break boot.
+    class Engine < ::Rails::Engine
+      isolate_namespace Rails::Hyperdrive
+
+      initializer "hyperdrive.warn_outside_development" do
+        unless Rails::Hyperdrive.dev_mode?
+          msg = "[hyperdrive] loaded outside development (Rails.env=#{::Rails.env}); MCP endpoints will return 403"
+          if ::Rails.logger
+            ::Rails.logger.warn(msg)
+          else
+            warn(msg)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/index_document.rb

@@ -0,0 +1,49 @@
+module Rails
+  module Hyperdrive
+    # Renders index.md — the list of `@`-includes that decides which guidelines
+    # load eagerly. Pure: the caller supplies the existing content and writes
+    # the result.
+    module IndexDocument
+      GUIDELINE_PREFIX = "@guidelines/".freeze
+
+      Rendered = Struct.new(:content, :guidelines, keyword_init: true)
+
+      module_function
+
+      # previously_installed are the guideline basenames the lock already
+      # records. A guideline whose line the user deleted from an existing
+      # index.md is not re-added.
+      def render(guidelines:, existing:, previously_installed:)
+        included = guidelines.select do |g|
+          next true if existing.nil?
+          next true unless previously_installed.include?(g[:base])
+          existing.include?("#{GUIDELINE_PREFIX}#{g[:base]}")
+        end
+
+        lines = included.map { |g| "#{GUIDELINE_PREFIX}#{g[:base]}" }.sort
+
+        Rendered.new(
+          content: lines.empty? ? "" : lines.join("\n") + "\n",
+          # Only guidelines referenced by index.md load into context, so they
+          # alone make up the eager footprint.
+          guidelines: included.map { |g| { name: g[:base], body: g[:body] } }
+        )
+      end
+
+      # Amends an existing index in place, returning nil when there is nothing
+      # to add. Existing lines carry over untouched, so an orphan keeps its
+      # inclusion.
+      def amend(existing:, added:)
+        return nil if existing.nil?
+
+        lines = added.map { |base| "#{GUIDELINE_PREFIX}#{base}" }
+        return nil if lines.empty?
+
+        current = existing.split("\n").map(&:strip).reject(&:empty?)
+        return nil if (lines - current).empty?
+
+        (current + lines).uniq.sort.join("\n") + "\n"
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/install_layout.rb

@@ -0,0 +1,45 @@
+module Rails
+  module Hyperdrive
+    # The one place install paths and artifact names are built and parsed.
+    # Must stay require-free: the MCP server loads it and must not drag in the
+    # install machinery.
+    module InstallLayout
+      SKILLS_DIR = ".claude/skills".freeze
+      HYPERDRIVE_DIR = ".claude/hyperdrive".freeze
+      INDEX_PATH = "#{HYPERDRIVE_DIR}/index.md".freeze
+      LOCK_PATH = ".hyperdrive/lock.yml".freeze
+
+      ARTIFACT_TYPES = { "skill" => :skill, "skill_support" => :skill_support, "guideline" => :guideline }.freeze
+
+      module_function
+
+      def dest_for(type, final_name)
+        case type
+        when :skill     then "#{SKILLS_DIR}/#{final_name}/SKILL.md"
+        when :guideline then "#{HYPERDRIVE_DIR}/guidelines/#{final_name}.md"
+        end
+      end
+
+      def installed_name(type, dest)
+        case type
+        when :skill         then File.basename(File.dirname(dest))
+        when :skill_support then dest.split("/")[2] # .claude/skills/<name>/<relpath>
+        when :guideline     then File.basename(dest, ".md")
+        end
+      end
+
+      def skill_dir_of(dest)
+        segments = dest.split("/")
+        File.join(*segments[0, 3]) # .claude/skills/<name>
+      end
+
+      def postfixed_name(name, source_gem)
+        "#{name}--#{source_gem}"
+      end
+
+      def base_name(name)
+        name.split("--").first.to_s
+      end
+    end
+  end
+end