rails-hyperdrive 0.6.0 → 0.7.0

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