rails-hyperdrive 0.5.0 → 0.7.0

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

@@ -20,12 +20,15 @@ module Rails
         MCP_SERVER_KEY = "rails-hyperdrive".freeze
 
         GEMFILE = "Gemfile".freeze
-        BUNDLER_PLUGIN = "bundler-rails-hyperdrive".freeze
+        BUNDLER_PLUGIN = "bundler-hyperdrive".freeze
 
+        # 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 :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 :skip_content,  type: :boolean, default: false, desc: "Skip all .claude content, CLAUDE.md, and the lockfile; leave the .mcp.json, .gitignore, Gemfile, and mount steps."
+        class_option :skip_mcp,      type: :boolean, default: false, desc: "Skip MCP setup entirely; write no .mcp.json entry and no engine mount."
         class_option :dry_run,       type: :boolean, default: false, desc: "Show what would change; write nothing."
 
         def verify_environment
@@ -39,6 +42,8 @@ module Rails
         # The write is forced: Thor's conflict prompt would otherwise block the
         # run waiting on stdin.
         def write_mcp_json
+          return if options[:skip_mcp]
+
           existing = mcp_json_on_disk
           document = existing ? parse_mcp_json(existing) : {}
           return if document.nil?
@@ -77,12 +82,9 @@ module Rails
           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
+          return if options[:skip_mcp]
+
           routes_file = "config/routes.rb"
           unless File.exist?(::Rails.root.join(routes_file))
             say_status :skip, "no #{routes_file} found; skipping engine mount", :yellow
@@ -110,17 +112,30 @@ module Rails
         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"
+          if options[:skip_mcp]
+            say "  MCP: skipped (--skip-mcp)"
+          else
+            say "  Mount: #{mount_path} (in config/routes.rb)"
+            say "  Server: #{::Rails::Hyperdrive::McpServer::TOOLS.size} MCP tools at http://localhost:3000#{mount_path}/mcp"
+          end
           runner.summary_lines.each { |line| say line } unless options[:skip_content]
+          # Every next step is about reaching the MCP endpoint.
+          return if options[:skip_mcp]
+
           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"
+          say "    3. Verify the connection: #{connection_check_command}"
         end
 
         no_tasks do
+          def connection_check_command
+            "curl -s http://localhost:3000#{mount_path}/mcp " \
+              "-H 'Content-Type: application/json' -H 'Accept: application/json' " \
+              "-d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}'"
+          end
+
           def mcp_json_on_disk
             abs = ::Rails.root.join(MCP_JSON_PATH)
             File.exist?(abs) ? File.read(abs) : nil

data/lib/generators/hyperdrive/install_summary.rb

@@ -4,8 +4,8 @@ module Rails
   module Generators
     module Hyperdrive
       module InstallSummary
-        KIND_WIDTH = "guideline".length
-        KIND_ORDER = %w[skill guideline].freeze
+        KIND_ORDER = ::Rails::Hyperdrive::InstallLayout.content_kinds.map(&:lock_kind).freeze
+        KIND_WIDTH = KIND_ORDER.map(&:length).max
 
         module_function
 
@@ -38,7 +38,7 @@ module Rails
 
         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")}"
+          "Installed #{KIND_ORDER.map { |kind| quantify(counts[kind].to_i, kind) }.join(", ")}"
         end
 
         def group_by_source(entries)

data/lib/generators/hyperdrive/sync/USAGE

@@ -1,9 +1,10 @@
 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 (skills to .claude/skills/, guidelines to
-        .claude/hyperdrive/guidelines/)
+      - discovers companion-gem skills, guidelines, agents, and commands in the
+        bundle and installs them (skills to .claude/skills/, guidelines to
+        .claude/hyperdrive/guidelines/, agents to .claude/agents/, commands to
+        .claude/commands/)
       - 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
@@ -24,8 +25,9 @@ Description:
     upstream wholesale. Either way the next sync is quiet: the lock already
     records the delivered upstream, so the same version is never re-offered.
 
-    Touches no bootstrap artifact: .mcp.json, the engine mount, the optional
-    initializer, and .gitignore belong to hyperdrive:init and are left alone.
+    Touches no bootstrap artifact: .mcp.json, the engine mount, the Gemfile
+    plugin directive, and .gitignore belong to hyperdrive:init and are left
+    alone.
 
 Examples:
     bin/rails hyperdrive:sync

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

@@ -6,7 +6,7 @@ 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).
+      # (.mcp.json, the engine mount, the .gitignore rule).
       class SyncGenerator < ::Rails::Generators::Base
         include ContentSyncSupport
 

data/lib/generators/hyperdrive/sync_runner.rb

@@ -32,18 +32,18 @@ module Rails
 
         def discover_artifacts(skip: false)
           @artifacts ||= skip ? [] : ::Rails::Hyperdrive::BundlerArtifactDiscovery.discover(
-            warnings: warnings, enabled_gems: enabled_gems, notices: notices
+            enabled_gems: enabled_gems, report: report
           )
         end
 
         def install(mode:)
+          verify_lock_schema!
           @pipeline = ::Rails::Hyperdrive::InstallPipeline.new(
             root: root,
             shell: @shell,
             artifacts: discover_artifacts,
             mode: mode,
-            warnings: warnings,
-            notices: notices
+            report: report
           )
           @pipeline.call
         end
@@ -54,24 +54,34 @@ module Rails
 
         private
 
+        # Raised from install, so it stops the run before any content write —
+        # a dry run included.
+        def verify_lock_schema!
+          return unless lock.schema_ahead?
+
+          message = lock.schema_ahead_message(::Rails::Hyperdrive::InstallLayout::LOCK_PATH)
+          @shell.say_status :error, message, :red
+          raise Thor::Error, "hyperdrive: #{message}"
+        end
+
         # 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 ||= []
+        def report
+          @report ||= ::Rails::Hyperdrive::BundlerArtifactDiscovery::Report.new
         end
 
-        def notices
-          @notices ||= []
+        def lock
+          @lock ||= ::Rails::Hyperdrive::LockFile.load(
+            File.join(root, ::Rails::Hyperdrive::InstallLayout::LOCK_PATH)
+          )
         end
 
         def enabled_gems
-          @enabled_gems ||= ::Rails::Hyperdrive::LockFile.load(
-            File.join(root, ::Rails::Hyperdrive::InstallLayout::LOCK_PATH)
-          ).enabled_gems
+          lock.enabled_gems
         end
 
         def lock_entries

data/lib/hyperdrive/skill_tasks.rb

@@ -0,0 +1,39 @@
+# Rake tasks for companion gem repos: add `require "hyperdrive/skill_tasks"`
+# to the Rakefile. Every task takes an optional gemspec-path argument, e.g.
+# rake "hyperdrive:skills:render[path/to/name.gemspec]".
+require "rake"
+require "rails/hyperdrive/canonical_skill_render"
+require "rails/hyperdrive/manifest_lint"
+
+namespace :hyperdrive do
+  namespace :skills do
+    desc "Render each SKILL.md.erb template to its canonical static SKILL.md"
+    task :render, [:gemspec] do |_t, args|
+      written = Rails::Hyperdrive::CanonicalSkillRender.write(gemspec: args[:gemspec])
+      written.each { |r| puts "render #{r.dest}" }
+      puts "no skill templates found" if written.empty?
+    end
+
+    desc "Fail when a canonical skill file is stale, or raw ERB sits under a public skills root"
+    task :check, [:gemspec] do |_t, args|
+      roots = Rails::Hyperdrive::CanonicalSkillRender.resolve_roots(gemspec: args[:gemspec])
+      stale = Rails::Hyperdrive::CanonicalSkillRender.stale(roots: roots)
+      raw = Rails::Hyperdrive::CanonicalSkillRender.public_erb_templates(roots: roots)
+      stale.each { |r| warn "stale: #{r.dest}" }
+      raw.each { |p| warn "raw ERB: #{p}" }
+      abort "#{stale.size} canonical skill file(s) stale; run `rake hyperdrive:skills:render`" unless stale.empty?
+      abort "#{raw.size} ERB template(s) under a public skills root; move them to the template directory" unless raw.empty?
+      puts "canonical skill files up to date"
+    end
+  end
+
+  namespace :manifest do
+    desc "Fail on unknown keys, unparsable gating, or entries naming nothing shipped in hyperdrive.yml"
+    task :check, [:gemspec] do |_t, args|
+      result = Rails::Hyperdrive::ManifestLint.check(gemspec: args[:gemspec])
+      result.problems.each { |p| warn "#{result.manifest}: #{p}" }
+      abort "#{result.problems.size} problem(s) in #{result.manifest}" unless result.problems.empty?
+      puts result.manifest ? "#{result.manifest} is clean" : "no hyperdrive.yml; nothing to lint"
+    end
+  end
+end

data/lib/rails/commands/hyperdrive/hyperdrive_command.rb

@@ -0,0 +1,59 @@
+require "rails/command"
+require "rails/generators"
+require "generators/hyperdrive/install/install_generator"
+require "generators/hyperdrive/sync/sync_generator"
+require "generators/hyperdrive/discover/discover_generator"
+
+module Rails
+  module Command
+    # The generators are the sole authority on option parsing, defaults, and
+    # validation; this class only forwards argv and renders `--help`.
+    class HyperdriveCommand < Base
+      namespace "hyperdrive"
+
+      # Mirrors a generator's own flags so the help surface cannot drift from
+      # what the generator actually accepts. Thor's runtime options are
+      # excluded: they are inherited plumbing, not part of this command.
+      def self.mirror_generator_options(klass)
+        klass.class_options.each do |name, option|
+          next if ::Rails::Generators::Base.class_options.key?(name)
+          method_options[name] = option
+        end
+      end
+
+      # Thor treats a leading `--` as an options terminator, so with `-- --merge`
+      # the flag lands in positional args and `options[:merge]` is false. Both
+      # spellings must reach the generator identically.
+      def initialize(args = [], local_options = {}, config = {})
+        super
+        @argv = args + (local_options.is_a?(Array) ? local_options : [])
+        @argv = @argv.drop(1) if @argv.first == "--"
+      end
+
+      desc "init", "Install Rails Hyperdrive into this app (writes .mcp.json, CLAUDE.md, companion content, mounts engine)"
+      mirror_generator_options ::Rails::Generators::Hyperdrive::InstallGenerator
+      def init(*)
+        start_generator("install", "InstallGenerator")
+      end
+
+      desc "sync", "Sync Rails Hyperdrive content (skills, guidelines, agents, commands, index.md, lockfile); locally-edited files are preserved"
+      mirror_generator_options ::Rails::Generators::Hyperdrive::SyncGenerator
+      def sync(*)
+        start_generator("sync", "SyncGenerator")
+      end
+
+      desc "discover", "Suggest uninstalled rails-hyperdrive companion gems for this app's stack (networked, cached)"
+      mirror_generator_options ::Rails::Generators::Hyperdrive::DiscoverGenerator
+      def discover(*)
+        start_generator("discover", "DiscoverGenerator")
+      end
+
+      no_commands do
+        def start_generator(name, generator)
+          require_application!
+          ::Rails::Generators::Hyperdrive.const_get(generator).start(@argv)
+        end
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/ancestor_locator.rb

@@ -1,6 +1,7 @@
 require "bundler"
 require "rails/hyperdrive/bundler_artifact_discovery"
 require "rails/hyperdrive/drift_verdict"
+require "rails/hyperdrive/install_layout"
 require "rails/hyperdrive/skill_template"
 
 module Rails
@@ -49,19 +50,15 @@ module Rails
       end
 
       def install_ready(body, kind:, final_name:)
-        case kind.to_s
-        when "skill"
-          ready = BundlerArtifactDiscovery.install_ready_body(
-            BundlerArtifactDiscovery::Artifact.new(artifact_type: :skill, body: body)
-          )
-          final_name ? ready.sub(/^name:\s*.+$/, "name: #{final_name}") : ready
-        when "guideline"
-          BundlerArtifactDiscovery.install_ready_body(
-            BundlerArtifactDiscovery::Artifact.new(artifact_type: :guideline, body: body)
-          )
-        else
-          body
-        end
+        type = InstallLayout::ARTIFACT_TYPES[kind.to_s]
+        descriptor = type && InstallLayout.kind(type)
+        return body unless descriptor
+
+        ready = BundlerArtifactDiscovery.install_ready_body(
+          BundlerArtifactDiscovery::Artifact.new(artifact_type: type, body: body)
+        )
+        return ready unless final_name && descriptor.collision_rewrites_name
+        ready.sub(/^name:\s*.+$/, "name: #{final_name}")
       end
 
       def resolved_bundle

data/lib/rails/hyperdrive/artifact_status.rb

@@ -10,26 +10,34 @@ module Rails
     class ArtifactStatus
       STATES = %i[installed missing outdated orphaned].freeze
 
-      Entry = Struct.new(:path, :state, :artifact, :locked_source, :bundle_source, keyword_init: true) do
+      Entry = Struct.new(:path, :state, :artifact, :locked_source, :bundle_source, :source_gem, :source_bundled,
+        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} (no longer shipped by #{locked_source})"
+          when :orphaned then "#{path} (#{orphan_reason})"
           else path
           end
         end
+
+        private
+
+        def orphan_reason
+          LockFile.orphan_reason(source_label: locked_source, source_gem: source_gem, bundled: source_bundled)
+        end
       end
 
-      def self.compare(root:, artifacts:)
-        new(root: root, artifacts: artifacts).tap(&:compare)
+      def self.compare(root:, artifacts:, bundled_gems: [])
+        new(root: root, artifacts: artifacts, bundled_gems: bundled_gems).tap(&:compare)
       end
 
       attr_reader :entries
 
-      def initialize(root:, artifacts:)
+      def initialize(root:, artifacts:, bundled_gems: [])
         @root = File.expand_path(root.to_s)
         @artifacts = artifacts
+        @bundled_gems = Array(bundled_gems).map(&:to_s)
         @entries = []
       end
 
@@ -63,11 +71,12 @@ module Rails
           # 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)
+          next if type && InstallPlan.disabled_dest?(lock, type, locked.path, source_gem: locked.source_gem)
 
           @entries << Entry.new(
             path: locked.path, state: :orphaned, artifact: locked.kind&.to_sym,
-            locked_source: locked.source_label, bundle_source: nil
+            locked_source: locked.source_label, bundle_source: nil,
+            source_gem: locked.source_gem, source_bundled: @bundled_gems.include?(locked.source_gem.to_s)
           )
         end
 

data/lib/rails/hyperdrive/auto_install.rb

@@ -13,7 +13,8 @@ module Rails
     module AutoInstall
       DEVELOPMENT = "development".freeze
 
-      Result = Struct.new(:installed, :outdated, :orphaned, :unwired, :skipped, :error, keyword_init: true) do
+      Result = Struct.new(:installed, :outdated, :orphaned, :unwired, :advisories, :fence_warnings,
+        :halted, :skipped, :error, keyword_init: true) do
         def ran?
           skipped.nil?
         end
@@ -24,6 +25,8 @@ module Rails
 
         def messages
           return [] unless ran?
+          return [halted] if halted
+
           lines = []
           unless Array(installed).empty?
             lines << "installed #{installed.size} artifact(s):"
@@ -35,6 +38,10 @@ module Rails
             lines << "#{stale.size} artifact(s) need attention — run bin/rails hyperdrive:sync"
             stale.each { |entry| lines << "  #{entry}" }
           end
+          # An advisory names content that installed but not as the manifest
+          # asked; ordinary skips are init/sync's to report, not a bundle
+          # install's.
+          (Array(advisories) | Array(fence_warnings)).each { |warning| lines << warning }
           lines
         end
       end
@@ -47,9 +54,12 @@ module Rails
         return skip(:not_development) unless development?(env)
         return skip(:not_initialized) unless File.exist?(File.join(root, InstallLayout::LOCK_PATH))
 
-        enabled = LockFile.load(File.join(root, InstallLayout::LOCK_PATH)).enabled_gems
-        artifacts = BundlerArtifactDiscovery.discover(enabled_gems: enabled)
-        status = ArtifactStatus.compare(root: root, artifacts: artifacts)
+        lock = LockFile.load(File.join(root, InstallLayout::LOCK_PATH))
+        return halted(lock.schema_ahead_message(InstallLayout::LOCK_PATH)) if lock.schema_ahead?
+
+        report = BundlerArtifactDiscovery::Report.new
+        artifacts = BundlerArtifactDiscovery.discover(enabled_gems: lock.enabled_gems, report: report)
+        status = ArtifactStatus.compare(root: root, artifacts: artifacts, bundled_gems: report.bundled_gems)
 
         installed = []
         unwired = false
@@ -59,7 +69,8 @@ module Rails
             root: root,
             shell: InstallShell.new(root: root, io: io),
             artifacts: artifacts,
-            mode: :additive
+            mode: :additive,
+            report: report
           )
           installed = pipeline.call.installed
           # This runs from a bundle install, which must not edit CLAUDE.md, so a
@@ -68,7 +79,8 @@ module Rails
           unwired = pipeline.lock.claude_md_state.nil? && (installed & pipeline.lock.guideline_paths).any?
         end
 
-        Result.new(installed: installed, outdated: status.outdated, orphaned: status.orphaned, unwired: unwired)
+        Result.new(installed: installed, outdated: status.outdated, orphaned: status.orphaned,
+          unwired: unwired, advisories: report.advisories, fence_warnings: report.fence_warnings)
       rescue StandardError => e
         skip(:error, e)
       end
@@ -93,7 +105,13 @@ module Rails
       end
 
       def skip(reason, error = nil)
-        Result.new(installed: [], outdated: [], orphaned: [], skipped: reason, error: error)
+        Result.new(installed: [], outdated: [], orphaned: [], advisories: [], fence_warnings: [],
+          skipped: reason, error: error)
+      end
+
+      # A completed run that installed nothing and has a reason to print.
+      def halted(reason)
+        Result.new(installed: [], outdated: [], orphaned: [], advisories: [], fence_warnings: [], halted: reason)
       end
     end
   end