rails-hyperdrive 0.3.0

data/lib/generators/hyperdrive/content_sync_support.rb

@@ -0,0 +1,54 @@
+require "generators/hyperdrive/sync_runner"
+
+module Rails
+  module Generators
+    module Hyperdrive
+      # Thor registers every public method defined directly on a generator
+      # class as a runnable command, so these shared helpers must stay in an
+      # included module or private.
+      module ContentSyncSupport
+        # Routes InstallPipeline's writes through Thor, so its output and
+        # `--dry-run` handling cover installed content too.
+        class ThorShell
+          def initialize(generator)
+            @generator = generator
+          end
+
+          def create_file(path, content)
+            @generator.create_file(path, content, force: true)
+          end
+
+          def append_to_file(path, content)
+            @generator.append_to_file(path, content)
+          end
+
+          def remove_file(path)
+            @generator.remove_file(path)
+          end
+
+          def say_status(kind, message, color = nil)
+            @generator.say_status(kind, message, color)
+          end
+
+          def say(message = "")
+            @generator.say(message)
+          end
+        end
+
+        # Thor's file-writing helpers all read options[:pretend], so mapping
+        # --dry-run on read keeps it in force for every step regardless of
+        # which one runs first.
+        def options
+          opts = super
+          opts[:dry_run] ? opts.merge(pretend: true) : opts
+        end
+
+        private
+
+        def runner
+          @runner ||= SyncRunner.new(shell: ThorShell.new(self))
+        end
+      end
+    end
+  end
+end

data/lib/generators/hyperdrive/discover/discover_generator.rb

@@ -0,0 +1,103 @@
+require "rails/generators"
+require "rails/generators/base"
+require "rails/hyperdrive"
+require "rails/hyperdrive/companion_discovery"
+require "generators/hyperdrive/gitignore_support"
+
+module Rails
+  module Generators
+    module Hyperdrive
+      # Read-only with respect to the app: never edits the Gemfile and never installs gems.
+      class DiscoverGenerator < ::Rails::Generators::Base
+        include GitignoreSupport
+
+        CACHE_RULE = ::Rails::Hyperdrive::CompanionDiscovery::CACHE_RELATIVE_PATH
+
+        source_root __dir__
+
+        class_option :refresh, type: :boolean, default: false,
+          desc: "Ignore the cached results and re-query rubygems."
+
+        def verify_environment
+          return if defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+          say_status :error, "must be run inside a Rails app", :red
+          raise Thor::Error, "hyperdrive: not in a Rails app"
+        end
+
+        def ensure_cache_gitignored
+          ensure_gitignored(CACHE_RULE)
+        end
+
+        def discover_and_report
+          result = ::Rails::Hyperdrive::CompanionDiscovery.new(
+            lockfile_path: ::Rails.root.join("Gemfile.lock").to_s,
+            cache_path: ::Rails.root.join(CACHE_RULE).to_s,
+            refresh: options[:refresh]
+          ).run
+
+          if result.status == :unavailable
+            say_status :unavailable, "rubygems discovery unavailable — #{result.detail}; no cached results", :yellow
+            return
+          end
+
+          say_status :stale, "rubygems unreachable; showing #{format_age(result.age_seconds)} cached results — #{result.detail}", :yellow if result.status == :stale
+
+          report_suggestions(result.suggestions)
+          report_warnings(result.warnings)
+        end
+
+        no_tasks do
+          def report_suggestions(suggestions)
+            if suggestions.empty?
+              say_status :none, "no rails-hyperdrive companion gems found for your stack", :blue
+              return
+            end
+
+            say ""
+            say "Found gems with rails-hyperdrive content for your stack:"
+            suggestions.each { |s| say "  #{format_line(s)}" }
+
+            to_add = suggestions.reject(&:installed)
+            return if to_add.empty?
+
+            say ""
+            to_add.each { |s| say "Run: bundle add #{s.gem_name} --group=development" }
+            say "Then: bin/rails hyperdrive:init"
+          end
+
+          def format_line(suggestion)
+            marker = suggestion.installed ? "✓" : "!"
+            companion = "#{suggestion.gem_name} #{suggestion.version}"
+            lhs =
+              if suggestion.matched_target
+                "#{suggestion.matched_target} #{suggestion.matched_version}   → #{companion}"
+              else
+                "#{companion} (applies to any stack)"
+              end
+            status = suggestion.installed ? "(installed)" : "(suggested)"
+            artifacts =
+              if suggestion.installed || suggestion.artifacts.empty?
+                ""
+              else
+                " — ships #{suggestion.artifacts.join(" + ")}"
+              end
+            "#{marker} #{lhs}#{artifacts}  #{status}"
+          end
+
+          def report_warnings(warnings)
+            return if warnings.empty?
+            say ""
+            say_status :warn, "discovery skipped #{warnings.size} gem(s):", :yellow
+            warnings.each { |w| say "    - #{w}" }
+          end
+
+          def format_age(seconds)
+            return "cached" unless seconds
+            hours = (seconds / 3600.0).round
+            hours <= 1 ? "~1h-old" : "~#{hours}h-old"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/generators/hyperdrive/gitignore_support.rb

@@ -0,0 +1,28 @@
+module Rails
+  module Generators
+    module Hyperdrive
+      # Included as a module so its methods are not registered as Thor commands —
+      # Thor's method_added hook fires only for methods defined directly on the
+      # generator class.
+      module GitignoreSupport
+        GITIGNORE = ".gitignore".freeze
+
+        # The rule must name a specific file, never a directory — the lockfile
+        # in the same directory stays tracked.
+        def ensure_gitignored(rule)
+          abs = ::Rails.root.join(GITIGNORE)
+          unless File.exist?(abs)
+            create_file GITIGNORE, "#{rule}\n"
+            return
+          end
+
+          body = File.read(abs)
+          return if body.split("\n").any? { |line| line.strip == rule }
+
+          prefix = body.end_with?("\n") || body.empty? ? "" : "\n"
+          append_to_file GITIGNORE, "#{prefix}#{rule}\n"
+        end
+      end
+    end
+  end
+end

data/lib/generators/hyperdrive/install/USAGE

@@ -0,0 +1,22 @@
+Description:
+    Bootstraps Rails Hyperdrive in this app:
+      - adds the rails-hyperdrive server to .mcp.json (Claude Code config),
+        merging into any servers already configured there
+      - mounts Rails::Hyperdrive::Engine at /_hyperdrive in config/routes.rb (idempotent)
+      - discovers companion-gem skills + guidelines in the bundle and installs
+        them with audit headers (skills to .claude/skills/, guidelines to
+        .claude/hyperdrive/guidelines/)
+      - maintains the .claude/hyperdrive/index.md aggregator and injects one
+        @-include line into CLAUDE.md — both only while a companion gem ships
+        a guideline, and both removed when the last one goes
+      - tracks everything in .hyperdrive/lock.yml
+
+    Re-running re-syncs content and leaves locally-modified files untouched
+    (skip + warn). Routine content refresh is bin/rails hyperdrive:sync
+    (pass --overwrite to restore gem-shipped content).
+
+Examples:
+    bin/rails hyperdrive:init
+    bin/rails hyperdrive:init --mount-at /admin/hyperdrive
+    bin/rails hyperdrive:init --skip-content
+    bin/rails hyperdrive:init --dry-run

data/lib/generators/hyperdrive/install/install_generator.rb

@@ -0,0 +1,168 @@
+require "rails/generators"
+require "rails/generators/base"
+require "json"
+require "rails/hyperdrive/companion_discovery"
+require "rails/hyperdrive/mcp_server"
+require "generators/hyperdrive/content_sync_support"
+require "generators/hyperdrive/gitignore_support"
+
+module Rails
+  module Generators
+    module Hyperdrive
+      class InstallGenerator < ::Rails::Generators::Base
+        include ContentSyncSupport
+        include GitignoreSupport
+
+        ENGINE_MOUNT_TOKEN = "Rails::Hyperdrive::Engine"
+        DEFAULT_MOUNT_AT = "/_hyperdrive".freeze
+
+        MCP_JSON_PATH = ".mcp.json".freeze
+        MCP_SERVER_KEY = "rails-hyperdrive".freeze
+
+        GEMFILE = "Gemfile".freeze
+        BUNDLER_PLUGIN = "bundler-rails-hyperdrive".freeze
+
+        source_root File.expand_path("templates", __dir__)
+
+        class_option :mount_at,      type: :string,  default: DEFAULT_MOUNT_AT, desc: "Engine mount path."
+        class_option :skip_content,  type: :boolean, default: false, desc: "Skip all .claude content, CLAUDE.md, and the lockfile; write only .mcp.json and the mount."
+        class_option :dry_run,       type: :boolean, default: false, desc: "Show what would change; write nothing."
+
+        def verify_environment
+          runner.verify_environment!
+        end
+
+        def discover_artifacts
+          runner.discover_artifacts(skip: options[:skip_content])
+        end
+
+        # The write is forced: Thor's conflict prompt would otherwise block the
+        # run waiting on stdin.
+        def write_mcp_json
+          existing = mcp_json_on_disk
+          document = existing ? parse_mcp_json(existing) : {}
+          return if document.nil?
+
+          (document["mcpServers"] ||= {})[MCP_SERVER_KEY] = mcp_server_entry
+          content = JSON.pretty_generate(document) + "\n"
+
+          if existing == content
+            say_status :unchanged, MCP_JSON_PATH, :blue
+          else
+            create_file MCP_JSON_PATH, content, force: true
+          end
+        end
+
+        def ignore_discover_cache
+          ensure_gitignored(::Rails::Hyperdrive::CompanionDiscovery::CACHE_RELATIVE_PATH)
+        end
+
+        # Any existing directive counts as registered — a path- or
+        # version-qualified line is a deliberate choice this must not
+        # duplicate or rewrite.
+        def register_bundler_plugin
+          gemfile = ::Rails.root.join(GEMFILE)
+          unless File.exist?(gemfile)
+            say_status :skip, "no #{GEMFILE} found; add plugin #{BUNDLER_PLUGIN.inspect} manually", :yellow
+            return
+          end
+
+          body = File.read(gemfile)
+          if body.match?(/^\s*plugin\s+["']#{BUNDLER_PLUGIN}["']/)
+            say_status :identical, "#{GEMFILE} (#{BUNDLER_PLUGIN} plugin already registered)", :blue
+            return
+          end
+
+          prefix = body.end_with?("\n") || body.empty? ? "" : "\n"
+          append_to_file GEMFILE, "#{prefix}plugin #{BUNDLER_PLUGIN.inspect}\n"
+        end
+
+        def write_initializer
+          return if mount_path == DEFAULT_MOUNT_AT
+          template "initializer.rb.tt", "config/initializers/hyperdrive.rb"
+        end
+
+        def mount_engine
+          routes_file = "config/routes.rb"
+          unless File.exist?(::Rails.root.join(routes_file))
+            say_status :skip, "no #{routes_file} found; skipping engine mount", :yellow
+            return
+          end
+
+          contents = File.read(::Rails.root.join(routes_file))
+          if contents.include?(ENGINE_MOUNT_TOKEN)
+            say_status :identical, "#{routes_file} (engine already mounted)", :blue
+            return
+          end
+
+          snippet = "  mount Rails::Hyperdrive::Engine => \"#{mount_path}\" if Rails.env.development?\n"
+          inject_into_file routes_file, snippet, after: /Rails\.application\.routes\.draw do\s*\n/
+        end
+
+        # `--skip-content` writes no lockfile either: the lock is a manifest of
+        # installed content, and an empty one would assert "zero files is the
+        # managed set". A later init or sync reconstructs the full state.
+        def sync_content
+          return if options[:skip_content]
+          runner.install(mode: :preserve)
+        end
+
+        def print_summary
+          say ""
+          say_status :done, "hyperdrive initialized", :green
+          say "  Mount: #{mount_path} (in config/routes.rb)"
+          say "  Server: #{::Rails::Hyperdrive::McpServer::TOOLS.size} MCP tools at http://localhost:3000#{mount_path}/mcp"
+          runner.summary_lines.each { |line| say line } unless options[:skip_content]
+          say ""
+          say "  Next steps:"
+          say "    1. bin/rails server"
+          say "    2. Open Claude Code in this directory; it will read .mcp.json"
+          say "    3. Verify the connection: curl http://localhost:3000#{mount_path}/mcp"
+        end
+
+        no_tasks do
+          def mcp_json_on_disk
+            abs = ::Rails.root.join(MCP_JSON_PATH)
+            File.exist?(abs) ? File.read(abs) : nil
+          end
+
+          def mcp_server_entry
+            {
+              "url" => "http://localhost:3000#{mount_path}/mcp",
+              "type" => "http"
+            }
+          end
+
+          # A file we can't parse is never overwritten — its contents are
+          # unrecoverable.
+          def parse_mcp_json(raw)
+            document = JSON.parse(raw)
+            return unmergeable_mcp_json("top-level value is not a JSON object") unless document.is_a?(Hash)
+
+            servers = document["mcpServers"]
+            unless servers.nil? || servers.is_a?(Hash)
+              return unmergeable_mcp_json('"mcpServers" is not a JSON object')
+            end
+
+            document
+          rescue JSON::ParserError => e
+            unmergeable_mcp_json(e.message.lines.first.to_s.strip)
+          end
+
+          def unmergeable_mcp_json(reason)
+            say_status :warn,
+              "#{MCP_JSON_PATH} left unchanged (#{reason}); fix it and re-run to add the #{MCP_SERVER_KEY} server",
+              :yellow
+            nil
+          end
+
+          def mount_path
+            raw = options[:mount_at].to_s
+            raw = "/" + raw unless raw.start_with?("/")
+            raw.length > 1 ? raw.chomp("/") : raw
+          end
+        end
+      end
+    end
+  end
+end

data/lib/generators/hyperdrive/install/templates/initializer.rb.tt

@@ -0,0 +1,3 @@
+Rails::Hyperdrive.configure do |c|
+  c.mount_at = "<%= mount_path %>"
+end

data/lib/generators/hyperdrive/install_summary.rb

@@ -0,0 +1,70 @@
+require "rails/hyperdrive/install_layout"
+
+module Rails
+  module Generators
+    module Hyperdrive
+      module InstallSummary
+        KIND_WIDTH = "guideline".length
+        KIND_ORDER = %w[skill guideline].freeze
+
+        module_function
+
+        # The lock is the authoritative set: it includes untouched,
+        # locally-modified, and orphaned files.
+        def lines(entries)
+          entries = entries.to_a
+          return [] if entries.empty?
+
+          support, listed = entries.partition { |e| e.kind.to_s == "skill_support" }
+          # A carried SKILL.md entry can record an older source than its
+          # supporting files, so counts key on the installed directory name,
+          # which is unique across sources.
+          support_counts = support
+            .group_by { |e| ::Rails::Hyperdrive::InstallLayout.installed_name(:skill_support, e.path.to_s) }
+            .transform_values(&:size)
+
+          out = ["  #{installed_counts(listed)}", ""]
+          group_by_source(listed).each do |source, group|
+            out << "    #{source}"
+            group.each do |entry|
+              name = display_name(entry)
+              count = entry.kind.to_s == "skill" ? support_counts[name].to_i : 0
+              suffix = count.positive? ? " (+#{quantify(count, "file")})" : ""
+              out << "      #{entry.kind.to_s.ljust(KIND_WIDTH)}  #{name}#{suffix}"
+            end
+          end
+          out
+        end
+
+        def installed_counts(entries)
+          counts = entries.group_by { |e| e.kind.to_s }.transform_values(&:size)
+          "Installed #{quantify(counts["skill"].to_i, "skill")}, #{quantify(counts["guideline"].to_i, "guideline")}"
+        end
+
+        def group_by_source(entries)
+          entries
+            .group_by { |e| e.source_label.to_s }
+            .sort_by { |source, group| [group.first.source_gem == "internal" ? 1 : 0, source] }
+            .map do |source, group|
+              [source, group.sort_by { |e| [KIND_ORDER.index(e.kind.to_s) || KIND_ORDER.size, display_name(e)] }]
+            end
+        end
+
+        def display_name(entry)
+          path = entry.path.to_s
+
+          # A kind outside the install layout can only come from a hand-edited
+          # lock, so it degrades to the filename instead of printing nothing.
+          type = ::Rails::Hyperdrive::InstallLayout::ARTIFACT_TYPES[entry.kind.to_s]
+          type ? ::Rails::Hyperdrive::InstallLayout.installed_name(type, path) : File.basename(path, ".md")
+        end
+
+        def quantify(count, noun)
+          "#{count} #{noun}#{"s" unless count == 1}"
+        end
+
+        private_class_method :installed_counts, :group_by_source, :display_name, :quantify
+      end
+    end
+  end
+end

data/lib/generators/hyperdrive/sync/USAGE

@@ -0,0 +1,21 @@
+Description:
+    Syncs Rails Hyperdrive content to match the current bundle (run after
+    `bundle update` or after adding a companion gem):
+      - discovers companion-gem skills + guidelines in the bundle and installs
+        them with audit headers (skills to .claude/skills/, guidelines to
+        .claude/hyperdrive/guidelines/)
+      - maintains the .claude/hyperdrive/index.md aggregator and the single
+        @-include line in CLAUDE.md — both only while a companion gem ships a
+        guideline, and both removed when the last one goes
+      - tracks everything in .hyperdrive/lock.yml
+
+    Locally-modified files are left untouched (skip + warn). Pass --overwrite
+    to restore them to the gem-shipped content.
+
+    Touches no bootstrap artifact: .mcp.json, the engine mount, the optional
+    initializer, and .gitignore belong to hyperdrive:init and are left alone.
+
+Examples:
+    bin/rails hyperdrive:sync
+    bin/rails hyperdrive:sync --overwrite
+    bin/rails hyperdrive:sync --dry-run

data/lib/generators/hyperdrive/sync/sync_generator.rb

@@ -0,0 +1,40 @@
+require "rails/generators"
+require "rails/generators/base"
+require "generators/hyperdrive/content_sync_support"
+
+module Rails
+  module Generators
+    module Hyperdrive
+      # Content-only by contract: no step may write a bootstrap artifact
+      # (.mcp.json, the engine mount, the initializer, the .gitignore rule).
+      class SyncGenerator < ::Rails::Generators::Base
+        include ContentSyncSupport
+
+        # No templates are rendered; source_root exists so Rails resolves the
+        # sibling USAGE file for `--help`.
+        source_root File.expand_path("templates", __dir__)
+
+        class_option :overwrite, type: :boolean, default: false, desc: "Restore locally-modified managed files to the gem-shipped content."
+        class_option :dry_run,   type: :boolean, default: false, desc: "Show what would change; write nothing."
+
+        def verify_environment
+          runner.verify_environment!
+        end
+
+        def discover_artifacts
+          runner.discover_artifacts
+        end
+
+        def sync_content
+          runner.install(mode: options[:overwrite] ? :overwrite : :preserve)
+        end
+
+        def print_summary
+          say ""
+          say_status :done, "hyperdrive synced", :green
+          runner.summary_lines.each { |line| say line }
+        end
+      end
+    end
+  end
+end

data/lib/generators/hyperdrive/sync_runner.rb

@@ -0,0 +1,70 @@
+require "thor"
+require "rails/hyperdrive"
+require "rails/hyperdrive/bundler_artifact_discovery"
+require "rails/hyperdrive/install_pipeline"
+require "generators/hyperdrive/install_summary"
+
+module Rails
+  module Generators
+    module Hyperdrive
+      # Owns the init/sync sequence. Each phase is an idempotent memoizer and
+      # `install` forces the ones it needs, so no call order can install with a
+      # half-built input set.
+      class SyncRunner
+        def initialize(shell:, root: nil)
+          @shell = shell
+          @root = root&.to_s
+        end
+
+        def verify_environment!
+          unless defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+            @shell.say_status :error, "must be run inside a Rails app", :red
+            raise Thor::Error, "hyperdrive: not in a Rails app"
+          end
+          unless ::Rails.respond_to?(:env) && ::Rails.env.development?
+            env = ::Rails.respond_to?(:env) ? ::Rails.env.to_s : "unknown"
+            warn "hyperdrive: must run with Rails.env=development (current: #{env})"
+            raise Thor::Error, "hyperdrive: refuse to run outside development (Rails.env=#{env})"
+          end
+        end
+
+        def discover_artifacts(skip: false)
+          @artifacts ||= skip ? [] : ::Rails::Hyperdrive::BundlerArtifactDiscovery.discover(warnings: warnings)
+        end
+
+        def install(mode:)
+          @pipeline = ::Rails::Hyperdrive::InstallPipeline.new(
+            root: root,
+            shell: @shell,
+            artifacts: discover_artifacts,
+            mode: mode,
+            warnings: warnings
+          )
+          @pipeline.call
+        end
+
+        def summary_lines
+          InstallSummary.lines(lock_entries)
+        end
+
+        private
+
+        # Resolved lazily so verify_environment! can report a missing Rails app
+        # before anything dereferences ::Rails.root.
+        def root
+          @root ||= ::Rails.root.to_s
+        end
+
+        def warnings
+          @warnings ||= []
+        end
+
+        def lock_entries
+          entries = []
+          @pipeline&.lock&.each_entry { |e| entries << e }
+          entries
+        end
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/artifact_status.rb

@@ -0,0 +1,86 @@
+require "rails/hyperdrive/drift_verdict"
+require "rails/hyperdrive/install_layout"
+require "rails/hyperdrive/install_plan"
+require "rails/hyperdrive/lock_file"
+
+module Rails
+  module Hyperdrive
+    # The comparison is against the lock manifest alone — installed files are
+    # never read, so an edited or deleted file does not change a verdict.
+    class ArtifactStatus
+      STATES = %i[installed missing outdated orphaned].freeze
+
+      Entry = Struct.new(:path, :state, :artifact, :locked_source, :bundle_source, keyword_init: true) do
+        def to_s
+          case state
+          when :missing  then "#{path} (from #{bundle_source})"
+          when :outdated then "#{path} (#{locked_source} → #{bundle_source})"
+          when :orphaned then "#{path} (source #{locked_source} no longer in bundle)"
+          else path
+          end
+        end
+      end
+
+      def self.compare(root:, artifacts:)
+        new(root: root, artifacts: artifacts).tap(&:compare)
+      end
+
+      attr_reader :entries
+
+      def initialize(root:, artifacts:)
+        @root = File.expand_path(root.to_s)
+        @artifacts = artifacts
+        @entries = []
+      end
+
+      def compare
+        lock = LockFile.load(File.join(@root, InstallLayout::LOCK_PATH))
+        offered = {}
+
+        InstallPlan.build(@artifacts, lock: lock).entries.each do |plan_entry|
+          offered[plan_entry.dest] = [DriftVerdict.body_sha(plan_entry.install_ready_body), plan_entry.source_label, plan_entry.type]
+          plan_entry.support_files.each do |file|
+            offered[file[:dest]] = [DriftVerdict.body_sha(file[:body]), plan_entry.source_label, :skill_support]
+          end
+        end
+
+        offered.each do |path, (gem_sha, source_label, type)|
+          locked = lock.entry(path)
+          state =
+            if locked.nil? then :missing
+            elsif locked.source_sha == gem_sha then :installed
+            else :outdated
+            end
+          @entries << Entry.new(
+            path: path, state: state, artifact: type,
+            locked_source: locked&.source_label, bundle_source: source_label
+          )
+        end
+
+        lock.each_entry do |locked|
+          next if offered.key?(locked.path)
+
+          # A disabled artifact left on disk was reported at install time; the
+          # bundle still ships it, so it is not an orphan.
+          type = InstallLayout::ARTIFACT_TYPES[locked.kind]
+          next if type && InstallPlan.disabled_dest?(lock, type, locked.path)
+
+          @entries << Entry.new(
+            path: locked.path, state: :orphaned, artifact: locked.kind&.to_sym,
+            locked_source: locked.source_label, bundle_source: nil
+          )
+        end
+
+        self
+      end
+
+      STATES.each do |state|
+        define_method(state) { @entries.select { |e| e.state == state } }
+      end
+
+      def stale?
+        !missing.empty? || !outdated.empty? || !orphaned.empty?
+      end
+    end
+  end
+end