rails-hyperdrive 0.7.0 → 0.9.0

data/lib/generators/hyperdrive/sync_runner.rb

@@ -1,9 +1,11 @@
 require "thor"
 require "rails/hyperdrive"
 require "rails/hyperdrive/bundler_artifact_discovery"
+require "rails/hyperdrive/config_file"
 require "rails/hyperdrive/install_layout"
 require "rails/hyperdrive/install_pipeline"
 require "rails/hyperdrive/lock_file"
+require "rails/hyperdrive/sidecar_resolver"
 require "generators/hyperdrive/install_summary"
 
 module Rails
@@ -13,6 +15,16 @@ module Rails
       # `install` forces the ones it needs, so no call order can install with a
       # half-built input set.
       class SyncRunner
+        RESOLVER_HELP = <<~MSG.freeze
+          --resolve needs a resolver command; add one to %<config>s:
+
+            resolve:
+              command: <your tool> $PROMPT
+
+          Placeholders: $LOCAL $REMOTE $BASE $MERGED $SOURCE $PREVIOUS_SOURCE $KIND $PROMPT
+          (also exported as HYPERDRIVE_* environment variables). Exit 0 marks the sidecar resolved.
+        MSG
+
         def initialize(shell:, root: nil)
           @shell = shell
           @root = root&.to_s
@@ -43,17 +55,58 @@ module Rails
             shell: @shell,
             artifacts: discover_artifacts,
             mode: mode,
-            report: report
+            report: report,
+            config: config
           )
-          @pipeline.call
+          @result = @pipeline.call
+        end
+
+        # Raised before any content write, so --resolve with nothing to run
+        # fails without half-syncing the app.
+        def verify_resolver!
+          return if config.resolve_command
+
+          raise Thor::Error,
+            "hyperdrive: " + format(RESOLVER_HELP, config: ::Rails::Hyperdrive::InstallLayout::CONFIG_PATH)
+        end
+
+        def resolve_sidecars(dry_run: false)
+          @resolve_outcome = ::Rails::Hyperdrive::SidecarResolver.new(
+            root: root,
+            shell: @shell,
+            command: config.resolve_command,
+            lock: @pipeline.lock,
+            sidecars: Array(@result&.sidecars),
+            prompt_path: config.resolve_prompt,
+            dry_run: dry_run
+          ).call
         end
 
         def summary_lines
-          InstallSummary.lines(lock_entries)
+          InstallSummary.lines(lock_entries) + merge_lines + resolve_lines
         end
 
         private
 
+        def merge_lines
+          count = Array(@result&.merged).size
+          return [] if count.zero?
+
+          ["", "  Merged #{InstallSummary.quantify(count, "file")} by three-way merge; a clean merge is " \
+               "textually non-overlapping, not verified; review with `git diff`"]
+        end
+
+        def resolve_lines
+          outcome = @resolve_outcome
+          return [] unless outcome
+
+          parts = { "resolved" => outcome.resolved.size, "unresolved" => outcome.unresolved.size,
+                    "skipped" => outcome.skipped.size }.reject { |_label, count| count.zero? }
+          return ["", "  No sidecars to resolve"] if parts.empty?
+
+          ["", "  Sidecars: #{parts.map { |label, count| "#{count} #{label}" }.join(", ")}"]
+        end
+
         # Raised from install, so it stops the run before any content write —
         # a dry run included.
         def verify_lock_schema!
@@ -80,8 +133,14 @@ module Rails
           )
         end
 
+        def config
+          @config ||= ::Rails::Hyperdrive::ConfigFile.load(
+            File.join(root, ::Rails::Hyperdrive::InstallLayout::CONFIG_PATH)
+          )
+        end
+
         def enabled_gems
-          lock.enabled_gems
+          config.enabled_gems
         end
 
         def lock_entries

data/lib/rails/hyperdrive/ancestor_locator.rb

@@ -2,6 +2,7 @@ require "bundler"
 require "rails/hyperdrive/bundler_artifact_discovery"
 require "rails/hyperdrive/drift_verdict"
 require "rails/hyperdrive/install_layout"
+require "rails/hyperdrive/lock_file"
 require "rails/hyperdrive/skill_template"
 
 module Rails
@@ -34,6 +35,40 @@ module Rails
         nil
       end
 
+      # The sha gate runs against the ancestor an entry records while its
+      # sidecar is pending, not against the entry's own source, which by then
+      # names the pending delivery.
+      def locate_recorded_ancestor(lock_entry, final_name: nil, gem_paths: Gem.path, resolved: nil)
+        return nil unless lock_entry&.ancestor?
+
+        locate(
+          kind: lock_entry.kind,
+          relpath: lock_entry.ancestor_relpath,
+          lock_entry: LockFile::Entry.new(
+            source_gem: lock_entry.ancestor_gem,
+            source_version: lock_entry.ancestor_version,
+            source_sha: lock_entry.ancestor_sha
+          ),
+          final_name: final_name || final_name_from_dest(lock_entry),
+          gem_paths: gem_paths,
+          resolved: resolved
+        )
+      rescue StandardError
+        nil
+      end
+
+      # Only the kinds whose frontmatter carries the name need one, and for
+      # those the dest was built from it.
+      def final_name_from_dest(lock_entry)
+        type = InstallLayout::ARTIFACT_TYPES[lock_entry.kind.to_s]
+        descriptor = type && InstallLayout.kind(type)
+        return nil unless descriptor&.collision_rewrites_name
+
+        descriptor.installed_name(lock_entry.path.to_s)
+      rescue StandardError
+        nil
+      end
+
       def read_candidate(gem_root, relpath, kind:, resolved:)
         exact = File.join(gem_root, relpath)
         if File.file?(exact)
@@ -67,7 +102,7 @@ module Rails
         nil
       end
 
-      private_class_method :read_candidate, :install_ready, :resolved_bundle
+      private_class_method :final_name_from_dest, :read_candidate, :install_ready, :resolved_bundle
     end
   end
 end

data/lib/rails/hyperdrive/artifact_status.rb

@@ -1,3 +1,4 @@
+require "rails/hyperdrive/config_file"
 require "rails/hyperdrive/drift_verdict"
 require "rails/hyperdrive/install_layout"
 require "rails/hyperdrive/install_plan"
@@ -28,16 +29,17 @@ module Rails
         end
       end
 
-      def self.compare(root:, artifacts:, bundled_gems: [])
-        new(root: root, artifacts: artifacts, bundled_gems: bundled_gems).tap(&:compare)
+      def self.compare(root:, artifacts:, bundled_gems: [], config: nil)
+        new(root: root, artifacts: artifacts, bundled_gems: bundled_gems, config: config).tap(&:compare)
       end
 
       attr_reader :entries
 
-      def initialize(root:, artifacts:, bundled_gems: [])
+      def initialize(root:, artifacts:, bundled_gems: [], config: nil)
         @root = File.expand_path(root.to_s)
         @artifacts = artifacts
         @bundled_gems = Array(bundled_gems).map(&:to_s)
+        @config = config
         @entries = []
       end
 
@@ -45,7 +47,7 @@ module Rails
         lock = LockFile.load(File.join(@root, InstallLayout::LOCK_PATH))
         offered = {}
 
-        InstallPlan.build(@artifacts, lock: lock).entries.each do |plan_entry|
+        InstallPlan.build(@artifacts, config: config).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]
@@ -71,7 +73,7 @@ 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, source_gem: locked.source_gem)
+          next if type && InstallPlan.disabled_dest?(config, type, locked.path, source_gem: locked.source_gem)
 
           @entries << Entry.new(
             path: locked.path, state: :orphaned, artifact: locked.kind&.to_sym,
@@ -90,6 +92,12 @@ module Rails
       def stale?
         !missing.empty? || !outdated.empty? || !orphaned.empty?
       end
+
+      private
+
+      def config
+        @config ||= ConfigFile.load(File.join(@root, InstallLayout::CONFIG_PATH))
+      end
     end
   end
 end

data/lib/rails/hyperdrive/auto_install.rb

@@ -1,6 +1,7 @@
 require "bundler"
 require "rails/hyperdrive/artifact_status"
 require "rails/hyperdrive/bundler_artifact_discovery"
+require "rails/hyperdrive/config_file"
 require "rails/hyperdrive/install_layout"
 require "rails/hyperdrive/install_pipeline"
 require "rails/hyperdrive/install_shell"
@@ -14,7 +15,7 @@ module Rails
       DEVELOPMENT = "development".freeze
 
       Result = Struct.new(:installed, :outdated, :orphaned, :unwired, :advisories, :fence_warnings,
-        :halted, :skipped, :error, keyword_init: true) do
+        :config_warnings, :halted, :skipped, :error, keyword_init: true) do
         def ran?
           skipped.nil?
         end
@@ -27,7 +28,7 @@ module Rails
           return [] unless ran?
           return [halted] if halted
 
-          lines = []
+          lines = Array(config_warnings).dup
           unless Array(installed).empty?
             lines << "installed #{installed.size} artifact(s):"
             installed.each { |path| lines << "  #{path}" }
@@ -57,9 +58,14 @@ module Rails
         lock = LockFile.load(File.join(root, InstallLayout::LOCK_PATH))
         return halted(lock.schema_ahead_message(InstallLayout::LOCK_PATH)) if lock.schema_ahead?
 
+        config = ConfigFile.load(File.join(root, InstallLayout::CONFIG_PATH))
+        config_warnings = config.warnings.dup
+        config_warnings << lock.legacy_settings_message(InstallLayout::LOCK_PATH) if lock.legacy_settings?
+
         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)
+        artifacts = BundlerArtifactDiscovery.discover(enabled_gems: config.enabled_gems, report: report)
+        status = ArtifactStatus.compare(root: root, artifacts: artifacts, bundled_gems: report.bundled_gems,
+          config: config)
 
         installed = []
         unwired = false
@@ -70,7 +76,8 @@ module Rails
             shell: InstallShell.new(root: root, io: io),
             artifacts: artifacts,
             mode: :additive,
-            report: report
+            report: report,
+            config: config
           )
           installed = pipeline.call.installed
           # This runs from a bundle install, which must not edit CLAUDE.md, so a
@@ -80,7 +87,8 @@ module Rails
         end
 
         Result.new(installed: installed, outdated: status.outdated, orphaned: status.orphaned,
-          unwired: unwired, advisories: report.advisories, fence_warnings: report.fence_warnings)
+          unwired: unwired, advisories: report.advisories, fence_warnings: report.fence_warnings,
+          config_warnings: config_warnings)
       rescue StandardError => e
         skip(:error, e)
       end
@@ -106,12 +114,13 @@ module Rails
 
       def skip(reason, error = nil)
         Result.new(installed: [], outdated: [], orphaned: [], advisories: [], fence_warnings: [],
-          skipped: reason, error: error)
+          config_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)
+        Result.new(installed: [], outdated: [], orphaned: [], advisories: [], fence_warnings: [],
+          config_warnings: [], halted: reason)
       end
     end
   end

data/lib/rails/hyperdrive/bundler_artifact_discovery.rb

@@ -88,9 +88,7 @@ module Rails
             next
           end
           manifest = GemManifest.load(spec, warnings: report.warnings)
-          seen = Hash.new { |h, k| h[k] = [] }
-          each_artifact_path(spec, manifest: manifest, report: report) do |path, kind, support_root, key|
-            seen[kind.type] << key
+          seen = each_artifact_path(spec, manifest: manifest, report: report) do |path, kind, support_root, key|
             gate = manifest.gate(kind.type, key)
             artifact = parse(path, source_spec: spec, kind: kind, resolved: resolved,
               report: report, support_root: support_root, gate: gate, key: key, manifest: manifest)
@@ -111,20 +109,27 @@ module Rails
         end
       end
 
-      # Yields each candidate with its kind descriptor and its manifest join
-      # key: a directory-shaped kind's relpath from its root, a flat kind's
-      # filename. Keys are collected before parsing, so a candidate later
-      # dropped (e.g. an ERB render failure) still counts as known to the
-      # manifest.
+      # Yields each candidate with its kind descriptor and the manifest join key
+      # its gating is read under: a directory-shaped kind's relpath from its
+      # root, a flat kind's filename. Returns every key the manifest could have
+      # named a shipped artifact by, collected before parsing so a candidate
+      # later dropped (e.g. an ERB render failure) still counts as known.
       def each_artifact_path(spec, manifest:, report:)
+        seen = Hash.new { |h, k| h[k] = [] }
         InstallLayout.content_kinds.each do |kind|
           if kind.dir_shaped?
-            skill_paths(spec, manifest: manifest, report: report)
-              .each { |path, support_root, rel| yield path, kind, support_root, rel }
+            skill_paths(spec, manifest: manifest, report: report).each do |path, support_root, rel|
+              seen[kind.type] << rel
+              yield path, kind, support_root, rel
+            end
           else
-            flat_paths(spec, kind, manifest: manifest).each { |p| yield p, kind, nil, File.basename(p) }
+            seen[kind.type].concat(flat_keys(spec, kind, manifest: manifest))
+            flat_paths(spec, kind, manifest: manifest, report: report).each do |path|
+              yield path, kind, nil, flat_gate_key(path, kind, manifest, spec, report)
+            end
           end
         end
+        seen
       end
 
       # The staleness signal for gating detached from content: an entry
@@ -212,14 +217,60 @@ module Rails
           "supporting *.md.erb templates; static supporting files ship in the paired content directory"
       end
 
-      # One .md file per artifact, deduped by expanded path so overlapping roots
-      # yield each file once.
-      def flat_paths(spec, kind, manifest:)
+      # One file per artifact: everything shipped, minus the templates a static
+      # file already ships the rendered face of.
+      def flat_paths(spec, kind, manifest:, report:)
+        resolve_flat_ties(flat_candidates(spec, kind, manifest: manifest), report)
+      end
+
+      # Every filename a manifest may key one of the kind's artifacts by: the
+      # name as shipped, plus each template's rendered face. Templates the tie
+      # rule drops are included — the manifest names shipped files, not
+      # surviving ones.
+      def flat_keys(spec, kind, manifest:)
+        flat_candidates(spec, kind, manifest: manifest)
+          .flat_map { |path| [File.basename(path), File.basename(target_path(path))] }
+          .uniq
+      end
+
+      # Deduped by expanded path so overlapping roots yield each file once.
+      def flat_candidates(spec, kind, manifest:)
+        glob = kind.erb ? "{*.md,*.md.erb}" : "*.md"
         artifact_roots(spec, kind, manifest)
-          .flat_map { |root| Dir.glob(File.join(root, "*.md")) }
+          .flat_map { |root| Dir.glob(File.join(root, glob)) }
           .uniq { |path| File.expand_path(path) }
       end
 
+      # A flat kind is identified by its filename, so a static file and a
+      # template rendering to that name are the same artifact anywhere in the
+      # root set; the static one wins, never silently.
+      def resolve_flat_ties(paths, report)
+        paths.group_by { |path| File.basename(target_path(path)) }.flat_map do |face, group|
+          templates, static = group.partition { |path| erb_template?(path) }
+          next group if templates.empty? || static.empty?
+
+          templates.each { |path| report.skip "skip #{path}: #{face} takes precedence" }
+          static
+        end
+      end
+
+      # A templated artifact answers to its shipped *.md.erb name and to the
+      # rendered face it installs as; the exact spelling wins when a manifest
+      # carries both.
+      def flat_gate_key(path, kind, manifest, spec, report)
+        shipped = File.basename(path)
+        face = File.basename(target_path(path))
+        return shipped if face == shipped
+
+        keys = manifest.section_keys(kind.type)
+        return face if keys.include?(face) && !keys.include?(shipped)
+        if keys.include?(shipped) && keys.include?(face)
+          report.warn "#{spec.name}: manifest #{kind.section} keys '#{shipped}' and '#{face}' both gate " \
+                      "'#{face}'; using '#{shipped}'"
+        end
+        shipped
+      end
+
       # The manifest's directory override is searched in addition to the kind's
       # convention roots, never instead of them.
       def artifact_roots(spec, kind, manifest)
@@ -239,7 +290,7 @@ module Rails
 
         convention_root = File.join(spec.full_gem_path, "lib", spec.name, "hyperdrive")
         Dir.glob(File.join(convention_root, "skills", "**", "{SKILL.md,SKILL.md.erb}")).any? ||
-          Dir.glob(File.join(convention_root, "guidelines", "*.md")).any?
+          Dir.glob(File.join(convention_root, "guidelines", "{*.md,*.md.erb}")).any?
       end
 
       def metadata_present?(spec, key)
@@ -257,7 +308,7 @@ module Rails
 
         count = found.map { |p| File.dirname(p) }.uniq.size
         report.notices << "gem '#{spec.name}' ships #{count} skills.sh skill(s); add \"#{spec.name}\" to enabled: " \
-                          "in .hyperdrive/lock.yml and re-run bin/rails hyperdrive:sync to install them"
+                          "in #{InstallLayout::CONFIG_PATH} and re-run bin/rails hyperdrive:sync to install them"
       end
 
       # Frontmatter's schema is exactly name and description; any other key is
@@ -348,7 +399,7 @@ module Rails
       # the manifest; the manifest still keys its own entries by the shipped
       # filename.
       def prefixed_stem(path, kind, manifest)
-        stem = File.basename(path, ".md")
+        stem = File.basename(target_path(path), ".md")
         prefix = manifest.name_prefix(kind.type)
         prefix ? "#{prefix}-#{stem}" : stem
       end
@@ -629,6 +680,7 @@ module Rails
       end
 
       private_class_method :each_artifact_path, :warn_unknown_manifest_keys,
+                           :flat_paths, :flat_candidates, :resolve_flat_ties, :flat_gate_key,
                            :artifact_roots, :prefixed_stem, :templates_root,
                            :resolve_same_dir_tie, :pair_with_templates, :warn_template_extras,
                            :opted_in?, :metadata_present?, :notice_skills_sh_content,

data/lib/rails/hyperdrive/config_file.rb

@@ -0,0 +1,135 @@
+require "yaml"
+require "rails/hyperdrive/install_layout"
+
+module Rails
+  module Hyperdrive
+    # The hand-owned settings file: which artifacts never to install, and which
+    # gems to treat as companions. Fail-open — a malformed part warns and reads
+    # as absent, and nothing raises.
+    class ConfigFile
+      DISABLED_KEYS = { skill: "skills", guideline: "guidelines", agent: "agents", command: "commands" }.freeze
+
+      attr_reader :path, :warnings, :resolve_command, :resolve_prompt
+
+      def self.load(path)
+        new(path).tap(&:read)
+      end
+
+      def initialize(path)
+        @path = path.to_s
+        @disabled = empty_disabled
+        @enabled = []
+        @warnings = []
+      end
+
+      def exist?
+        File.file?(@path)
+      end
+
+      def read
+        return self unless File.file?(@path)
+
+        data = YAML.safe_load(File.read(@path))
+        return self if data.nil?
+        return warn_and_empty("root is not a map; reading it as empty") unless data.is_a?(Hash)
+
+        read_disabled(data["disabled"])
+        read_enabled(data["enabled"])
+        read_resolve(data["resolve"])
+        self
+      rescue StandardError => e
+        warn_and_empty("could not be parsed (#{first_line(e.message)}); reading it as empty")
+      end
+
+      def disabled?(type, name)
+        Array(@disabled[type.to_sym]).include?(name.to_s)
+      end
+
+      def enabled_gems
+        @enabled
+      end
+
+      private
+
+      def read_disabled(raw)
+        return if raw.nil?
+        return report("disabled: must be a map of kind to list; ignoring it") unless raw.is_a?(Hash)
+
+        DISABLED_KEYS.each do |type, key|
+          value = raw[key]
+          next if value.nil?
+          unless value.is_a?(Array)
+            report("disabled: #{key}: must be a list of names; ignoring it")
+            next
+          end
+          @disabled[type] = normalize(value)
+        end
+      end
+
+      def read_resolve(raw)
+        return if raw.nil?
+        return report("resolve: must be a map; ignoring it") unless raw.is_a?(Hash)
+
+        @resolve_command = read_resolve_command(raw["command"])
+        @resolve_prompt = read_resolve_prompt(raw["prompt"])
+      end
+
+      def read_resolve_command(value)
+        return nil if value.nil?
+        return value.strip if value.is_a?(String) && !value.strip.empty?
+
+        report("resolve: command: must be a non-empty string; ignoring it")
+        nil
+      end
+
+      # The prompt is read relative to the app root; a path that escapes it is
+      # refused.
+      def read_resolve_prompt(value)
+        return nil if value.nil?
+        unless value.is_a?(String) && !value.strip.empty?
+          report("resolve: prompt: must be a non-empty string; ignoring it")
+          return nil
+        end
+
+        prompt = value.strip
+        if prompt.split("/").include?("..") || prompt.start_with?("/")
+          report("resolve: prompt: must be a path inside the app; ignoring it")
+          return nil
+        end
+        prompt
+      end
+
+      def read_enabled(raw)
+        return if raw.nil?
+        return report("enabled: must be a list of gem names; ignoring it") unless raw.is_a?(Array)
+
+        @enabled = normalize(raw)
+      end
+
+      def normalize(list)
+        list.map { |name| name.to_s.strip }.reject(&:empty?).uniq
+      end
+
+      def warn_and_empty(message)
+        report(message)
+        @disabled = empty_disabled
+        @enabled = []
+        @resolve_command = nil
+        @resolve_prompt = nil
+        self
+      end
+
+      def report(message)
+        @warnings << "#{InstallLayout::CONFIG_PATH} #{message}"
+      end
+
+      def first_line(message)
+        message.to_s.lines.first.to_s.strip
+      end
+
+      def empty_disabled
+        DISABLED_KEYS.keys.each_with_object({}) { |type, h| h[type] = [] }
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/install_layout.rb

@@ -11,6 +11,7 @@ module Rails
       COMMANDS_DIR = ".claude/commands".freeze
       INDEX_PATH = "#{HYPERDRIVE_DIR}/index.md".freeze
       LOCK_PATH = ".hyperdrive/lock.yml".freeze
+      CONFIG_PATH = ".hyperdrive/config.yml".freeze
 
       DEFAULT_TARGET = :claude
 
@@ -22,7 +23,7 @@ module Rails
       # identified and validated, and where each target tool installs it.
       Kind = Struct.new(
         :type, :shape, :section, :key_label, :shipped_label, :dir_key, :prefix_key,
-        :convention_roots, :identity, :frontmatter, :install_body,
+        :convention_roots, :identity, :frontmatter, :install_body, :erb,
         :collision_rewrites_name, :eager, :name_from_dest, :dests,
         keyword_init: true
       ) do
@@ -63,6 +64,7 @@ module Rails
           identity: :frontmatter,
           frontmatter: :required,
           install_body: :verbatim,
+          erb: true,
           collision_rewrites_name: true,
           eager: false,
           name_from_dest: ->(dest) { File.basename(File.dirname(dest)) },
@@ -89,6 +91,7 @@ module Rails
           identity: :frontmatter,
           frontmatter: :required,
           install_body: :strip_frontmatter,
+          erb: true,
           collision_rewrites_name: false,
           eager: true,
           name_from_dest: ->(dest) { File.basename(dest, ".md") },
@@ -111,6 +114,7 @@ module Rails
           identity: :frontmatter,
           frontmatter: :required,
           install_body: :verbatim,
+          erb: true,
           collision_rewrites_name: true,
           eager: false,
           name_from_dest: ->(dest) { File.basename(dest, ".md") },
@@ -128,6 +132,7 @@ module Rails
           identity: :filename_stem,
           frontmatter: :optional,
           install_body: :verbatim,
+          erb: true,
           collision_rewrites_name: false,
           eager: false,
           name_from_dest: ->(dest) { File.basename(dest, ".md") },