rails-hyperdrive 0.8.0 → 0.9.0

data/lib/rails/hyperdrive/lock_file.rb

@@ -1,22 +1,36 @@
 require "yaml"
+require "rails/hyperdrive/install_layout"
 
 module Rails
   module Hyperdrive
     # installed_at is volatile metadata, never an input to any comparison.
     class LockFile
-      SCHEMA_VERSION = 2
+      SCHEMA_VERSION = 3
       STATE_PRESENT  = "present".freeze
       STATE_REMOVED  = "removed-by-user".freeze
 
-      DISABLED_KEYS = { skill: "skills", guideline: "guidelines", agent: "agents", command: "commands" }.freeze
-
       # In-memory form of one files: entry. On disk, source_gem and
       # source_version are a single "gem@version" string; the split/join lives
       # in this file only.
-      Entry = Struct.new(:path, :kind, :source_gem, :source_version, :source_sha, :installed_at, keyword_init: true) do
+      Entry = Struct.new(
+        :path, :kind, :source_gem, :source_version, :source_sha, :installed_at,
+        :ancestor_gem, :ancestor_version, :ancestor_sha, :ancestor_relpath,
+        keyword_init: true
+      ) do
         def source_label
           source_version ? "#{source_gem}@#{source_version}" : source_gem
         end
+
+        # The upstream the live file's edits descend from, recorded only while
+        # a sidecar delivery is pending.
+        def ancestor_label
+          return nil unless ancestor_gem
+          ancestor_version ? "#{ancestor_gem}@#{ancestor_version}" : ancestor_gem
+        end
+
+        def ancestor?
+          !ancestor_gem.nil? && !ancestor_sha.nil?
+        end
       end
 
       attr_reader :path, :schema_version
@@ -39,8 +53,7 @@ module Rails
         @claude_md_state = nil # nil = no lock has been written yet
         @files = {}            # path(String) => Entry
         @document = {}         # raw parsed YAML, kept so unknown keys survive
-        @disabled = empty_disabled
-        @enabled = []
+        @legacy_settings = false
         @schema_version = nil
       end
 
@@ -54,8 +67,7 @@ module Rails
         @schema_version = data["version"]
         claude_md = data["claude_md"]
         @claude_md_state = claude_md["state"] if claude_md.is_a?(Hash)
-        @disabled = parse_disabled(data["disabled"])
-        @enabled = parse_enabled(data["enabled"])
+        @legacy_settings = data.key?("disabled") || data.key?("enabled")
         Array(data["files"]).each do |raw|
           next unless raw.is_a?(Hash)
           entry = build_entry(raw)
@@ -79,6 +91,17 @@ module Rails
           "this installer supports #{SCHEMA_VERSION}); upgrade rails-hyperdrive"
       end
 
+      def legacy_settings?
+        @legacy_settings
+      end
+
+      def legacy_settings_message(display_path)
+        "#{display_path} carries disabled:/enabled:; those settings now live in " \
+          "#{InstallLayout::CONFIG_PATH} and are ignored here. Move them now: disabled " \
+          "artifacts install again, and artifacts from gems enabled only there are " \
+          "removed by the next init/sync"
+      end
+
       def entry(file_path)
         @files[file_path.to_s]
       end
@@ -91,35 +114,43 @@ module Rails
         @files.values.each(&block)
       end
 
-      def disabled?(type, name)
-        Array(@disabled[type.to_sym]).include?(name.to_s)
-      end
-
-      # Hand-editable list of gems the app opts into as companions.
-      def enabled_gems
-        @enabled
-      end
-
       # Adopt the state that is not derived from installed content, so
       # rewriting the file preserves it.
-      def carry_settings(other)
+      def carry_document(other)
         @document = other.document.dup
-        @disabled = other.disabled_lists.dup
-        @enabled = other.enabled_gems.dup
         self
       end
 
-      def upsert(path:, kind:, source_gem:, source_version:, source_sha:, installed_at:)
+      def upsert(path:, kind:, source_gem:, source_version:, source_sha:, installed_at:,
+                 ancestor_gem: nil, ancestor_version: nil, ancestor_sha: nil, ancestor_relpath: nil)
         @files[path.to_s] = Entry.new(
           path: path.to_s,
           kind: kind.to_s,
           source_gem: source_gem.to_s,
           source_version: source_version.to_s,
           source_sha: source_sha.to_s,
-          installed_at: installed_at.to_s
+          installed_at: installed_at.to_s,
+          ancestor_gem: ancestor_gem,
+          ancestor_version: ancestor_version,
+          ancestor_sha: ancestor_sha,
+          ancestor_relpath: ancestor_relpath
         )
       end
 
+      # Replaces the entry rather than mutating it, so an entry carried from a
+      # lock read earlier in the run keeps the values that run compared against.
+      def clear_ancestor(file_path)
+        entry = @files[file_path.to_s]
+        return unless entry&.ancestor_gem || entry&.ancestor_sha || entry&.ancestor_relpath
+
+        @files[entry.path] = entry.dup.tap do |cleared|
+          cleared.ancestor_gem = nil
+          cleared.ancestor_version = nil
+          cleared.ancestor_sha = nil
+          cleared.ancestor_relpath = nil
+        end
+      end
+
       def carry(entry)
         return unless entry && entry.path
         @files[entry.path] = entry
@@ -132,14 +163,16 @@ module Rails
         document = @document.merge(
           "version"   => SCHEMA_VERSION,
           "claude_md" => carried.merge("state" => @claude_md_state),
-          "disabled"  => DISABLED_KEYS.each_with_object({}) { |(type, key), h| h[key] = @disabled[type] },
-          "enabled"   => @enabled,
           "files"     => @files.values.sort_by(&:path).map { |e| serialize_entry(e) }
         )
         # A nil state means no import line is being managed. Recording one anyway
         # would make the next run read the absent line as a deletion the user
         # made, and never add it back.
         document.delete("claude_md") if @claude_md_state.nil?
+        # Every other unknown key round-trips; these two must not, or a lock
+        # would keep asserting settings nothing reads.
+        document.delete("disabled")
+        document.delete("enabled")
         document.to_yaml
       end
 
@@ -149,39 +182,22 @@ module Rails
         @document
       end
 
-      def disabled_lists
-        @disabled
-      end
-
       private
 
-      def empty_disabled
-        DISABLED_KEYS.keys.each_with_object({}) { |type, h| h[type] = [] }
-      end
-
-      def parse_disabled(raw)
-        return empty_disabled unless raw.is_a?(Hash)
-
-        DISABLED_KEYS.each_with_object({}) do |(type, key), h|
-          h[type] = Array(raw[key]).map { |name| name.to_s.strip }.reject(&:empty?).uniq
-        end
-      end
-
-      def parse_enabled(raw)
-        return [] unless raw.is_a?(Array)
-
-        raw.map { |name| name.to_s.strip }.reject(&:empty?).uniq
-      end
-
       def build_entry(raw)
         source_gem, source_version = split_source(raw["source"])
+        ancestor_gem, ancestor_version = split_source(raw["ancestor_source"])
         Entry.new(
           path: raw["path"],
           kind: raw["artifact"],
           source_gem: source_gem,
           source_version: source_version,
           source_sha: raw["source_sha"],
-          installed_at: raw["installed_at"]
+          installed_at: raw["installed_at"],
+          ancestor_gem: ancestor_gem,
+          ancestor_version: ancestor_version,
+          ancestor_sha: raw["ancestor_sha"],
+          ancestor_relpath: raw["ancestor_relpath"]
         )
       end
 
@@ -195,13 +211,19 @@ module Rails
       end
 
       def serialize_entry(entry)
-        {
+        raw = {
           "path"         => entry.path,
           "artifact"     => entry.kind,
           "source"       => entry.source_label,
-          "source_sha"   => entry.source_sha,
-          "installed_at" => entry.installed_at
+          "source_sha"   => entry.source_sha
         }
+        # installed_at is re-added after the optional keys so their absence
+        # leaves an entry's key order untouched.
+        raw["ancestor_source"] = entry.ancestor_label if entry.ancestor_label
+        raw["ancestor_sha"] = entry.ancestor_sha if entry.ancestor_sha
+        raw["ancestor_relpath"] = entry.ancestor_relpath if entry.ancestor_relpath
+        raw["installed_at"] = entry.installed_at
+        raw
       end
     end
   end

data/lib/rails/hyperdrive/resolve/prompt.md.erb

@@ -0,0 +1,47 @@
+You are resolving one file for the rails-hyperdrive installer.
+
+The file is a rails-hyperdrive-managed file of kind `<%= kind %>`; the new
+upstream version is shipped by <%= source %>.<% if previous_source && !previous_source.empty? %> The version the project
+last received came from <%= previous_source %>.<% end %> The project has edited its copy
+locally, so the local edits and the new upstream version have to be reconciled
+by hand.
+
+Inputs:
+
+- LOCAL:  <%= local %>
+  The project's current copy, including its local edits.
+- REMOTE: <%= remote %>
+  The new upstream copy, exactly as <%= source %> ships it. It contains none of
+  the local edits.
+<% if base -%>
+- BASE:   <%= base %>
+  The common ancestor: the upstream copy the local edits were made on top of.
+  Anything that differs between BASE and LOCAL is a local edit; anything that
+  differs between BASE and REMOTE is an upstream change.
+<% else -%>
+- BASE:   not available. There is no common ancestor to compare against, so
+  decide which differences are local edits by reading LOCAL and REMOTE.
+<% end -%>
+
+Write the reconciled file to:
+
+- MERGED: <%= merged %>
+  This is the same path as LOCAL, so you are editing the project's copy in
+  place.
+
+Rules:
+
+- Take every upstream change from REMOTE.
+- Keep every local customisation from LOCAL.
+- Where an upstream change and a local edit touch the same thing, keep the
+  local intent and express it in terms of the new upstream text.
+- Write a complete, valid file. No conflict markers, no commentary about the
+  merge, no placeholders, and nothing invented that appears in neither input.
+<% if kind == "skill" || kind == "agent" -%>
+- Keep the YAML frontmatter valid, and leave the `name:` line exactly as REMOTE
+  has it.
+<% end -%>
+- If you are not confident the result is correct, change nothing and exit with a
+  non-zero status.
+
+Exit 0 only when MERGED holds the reconciled file.

data/lib/rails/hyperdrive/resolve_prompt.rb

@@ -0,0 +1,42 @@
+require "erb"
+
+module Rails
+  module Hyperdrive
+    # Renders the text bound to $PROMPT for the resolver command. The binding
+    # is an ordinary object rather than a sandbox: a user-supplied template
+    # runs arbitrary Ruby with the privileges of whoever ran the sync.
+    module ResolvePrompt
+      DEFAULT_PATH = File.expand_path("resolve/prompt.md.erb", __dir__).freeze
+
+      KNOBS = %i[local remote base merged source previous_source kind].freeze
+
+      class Context
+        attr_reader(*KNOBS)
+
+        def initialize(local:, remote:, base:, merged:, source:, previous_source:, kind:)
+          @local = local
+          @remote = remote
+          @base = base
+          @merged = merged
+          @source = source
+          @previous_source = previous_source
+          @kind = kind
+        end
+
+        def template_binding
+          binding
+        end
+      end
+
+      module_function
+
+      def render(template, **knobs)
+        ERB.new(template, trim_mode: "-").result(Context.new(**knobs).template_binding)
+      end
+
+      def default_template
+        File.read(DEFAULT_PATH)
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/sidecar_resolver.rb

@@ -0,0 +1,215 @@
+require "open3"
+require "shellwords"
+require "tmpdir"
+require "rails/hyperdrive/ancestor_locator"
+require "rails/hyperdrive/drift_verdict"
+require "rails/hyperdrive/install_layout"
+require "rails/hyperdrive/resolve_prompt"
+
+module Rails
+  module Hyperdrive
+    # Hands each unresolved <dest>.new sidecar to the user's resolver command,
+    # git-mergetool style, and deletes the sidecar when it exits 0. Nothing here
+    # writes the lock: the sidecar's absence is the whole resolution signal.
+    class SidecarResolver
+      TOKENS = %w[LOCAL REMOTE BASE MERGED SOURCE PREVIOUS_SOURCE KIND PROMPT].freeze
+      TOKEN_PATTERN = /\$(#{TOKENS.sort_by { |t| -t.length }.join("|")})\b/
+
+      Outcome = Struct.new(:resolved, :unresolved, :skipped, keyword_init: true)
+
+      Candidate = Struct.new(:dest, :sidecar, :kind, :source, :previous_source, :ancestor, :delivered,
+        keyword_init: true)
+
+      def initialize(root:, shell:, command:, lock:, sidecars: [], prompt_path: nil, dry_run: false)
+        @root = File.expand_path(root.to_s)
+        @shell = shell
+        @command = command.to_s
+        @lock = lock
+        @sidecars = Array(sidecars)
+        @prompt_path = prompt_path
+        @dry_run = dry_run
+        @outcome = Outcome.new(resolved: [], unresolved: [], skipped: [])
+      end
+
+      def call
+        candidates.each { |candidate| process(candidate) }
+        @outcome
+      end
+
+      private
+
+      def candidates
+        written = @sidecars.to_h { |s| [s.dest.to_s, s] }
+        list = []
+        @lock.each_entry do |entry|
+          sidecar = InstallLayout.sidecar_path(entry.path)
+          delivered = written[entry.path.to_s]
+          # A dry run wrote no sidecar to disk, so this run's deliveries are
+          # only knowable from the pipeline result.
+          next unless delivered || File.file?(abs(sidecar))
+
+          list << Candidate.new(
+            dest: entry.path,
+            sidecar: sidecar,
+            kind: entry.kind.to_s,
+            source: entry.source_label.to_s,
+            # A sidecar left over from an earlier run has no struct, so the
+            # base comes back from the ancestor the lock recorded with it.
+            previous_source: delivered&.previous_source || entry.ancestor_label,
+            ancestor: delivered&.ancestor || AncestorLocator.locate_recorded_ancestor(entry),
+            delivered: !delivered.nil?
+          )
+        end
+        list
+      end
+
+      def process(candidate)
+        unless candidate.delivered || pristine?(candidate)
+          @outcome.skipped << candidate.dest
+          @shell.say_status :warn,
+            "#{candidate.sidecar} (sidecar locally modified; resolve or delete it by hand)", :yellow
+          return
+        end
+
+        tokens = command_tokens
+        return unresolved(candidate, "resolve: command: is not a valid command line") if tokens.nil?
+        return unresolved(candidate, "resolve: command: names no program") if tokens.empty?
+
+        if @dry_run
+          @shell.say_status :resolve, "#{candidate.dest} (would run #{tokens.first})", :yellow
+          return
+        end
+
+        run(candidate, tokens)
+      end
+
+      def command_tokens
+        Shellwords.split(@command)
+      rescue ArgumentError
+        nil
+      end
+
+      # A sidecar is machine-written only while it still hashes to the upstream
+      # the lock records as delivered; anything else is the user's own work.
+      def pristine?(candidate)
+        entry = @lock.entry(candidate.dest)
+        return false unless entry
+        DriftVerdict.disk_sha(abs(candidate.sidecar)) == entry.source_sha
+      rescue StandardError
+        false
+      end
+
+      def run(candidate, tokens)
+        Dir.mktmpdir("hyperdrive-resolve") do |dir|
+          base = write_base(candidate, dir)
+          values = values_for(candidate, base: base)
+          argv = substitute(tokens, values, base: base)
+          @shell.say_status :resolve, "#{candidate.dest} via #{argv.first}", :blue
+          _out, err, status = Open3.capture3(env_for(values), *argv, chdir: @root)
+          if status.success?
+            # Exit 0 is the tool's assertion that the file is resolved, so the
+            # sidecar goes even if the tool never wrote $MERGED.
+            resolved(candidate)
+          else
+            unresolved(candidate, "exit #{status.exitstatus}#{detail(err)}")
+          end
+        end
+      rescue StandardError => e
+        unresolved(candidate, first_line(e.message))
+      end
+
+      def resolved(candidate)
+        @shell.remove_file candidate.sidecar
+        @outcome.resolved << candidate.dest
+        @shell.say_status :resolved, candidate.dest, :green
+      end
+
+      def unresolved(candidate, reason)
+        @outcome.unresolved << { dest: candidate.dest, reason: reason }
+        @shell.say_status :unresolved, "#{candidate.dest} (#{reason})", :yellow
+      end
+
+      def write_base(candidate, dir)
+        return nil unless candidate.ancestor
+
+        File.join(dir, "base-#{File.basename(candidate.dest)}").tap do |file|
+          File.binwrite(file, candidate.ancestor)
+        end
+      end
+
+      # Substitution runs per token after the split, so a value holding spaces
+      # stays one argument.
+      def substitute(tokens, values, base:)
+        tokens.each_with_object([]) do |token, argv|
+          next if base.nil? && token == "$BASE"
+          argv << token.gsub(TOKEN_PATTERN) { values[Regexp.last_match(1)].to_s }
+        end
+      end
+
+      def env_for(values)
+        values.to_h { |name, value| ["HYPERDRIVE_#{name}", value] }
+      end
+
+      def values_for(candidate, base:)
+        live = abs(candidate.dest)
+        values = {
+          "LOCAL" => live,
+          "REMOTE" => abs(candidate.sidecar),
+          # A nil BASE substitutes empty and unsets HYPERDRIVE_BASE in the
+          # child, so an outer HYPERDRIVE_BASE can never leak into a run.
+          "BASE" => base,
+          "MERGED" => live,
+          "SOURCE" => candidate.source,
+          "PREVIOUS_SOURCE" => candidate.previous_source.to_s,
+          "KIND" => candidate.kind
+        }
+        values["PROMPT"] = prompt(candidate, base: base, values: values)
+        values
+      end
+
+      def prompt(candidate, base:, values:)
+        knobs = {
+          local: values["LOCAL"], remote: values["REMOTE"], base: base, merged: values["MERGED"],
+          source: candidate.source, previous_source: candidate.previous_source, kind: candidate.kind
+        }
+        template = user_template
+        return ResolvePrompt.render(template, **knobs) if template
+
+        ResolvePrompt.render(ResolvePrompt.default_template, **knobs)
+      rescue StandardError => e
+        raise unless template
+        @shell.say_status :warn,
+          "resolve: prompt: #{@prompt_path} could not be rendered (#{first_line(e.message)}); using the default prompt",
+          :yellow
+        @user_template = false
+        ResolvePrompt.render(ResolvePrompt.default_template, **knobs)
+      end
+
+      def user_template
+        return nil unless @prompt_path
+        return nil if @user_template == false
+
+        @user_template ||= File.read(abs(@prompt_path))
+      rescue StandardError => e
+        @shell.say_status :warn,
+          "resolve: prompt: #{@prompt_path} could not be read (#{first_line(e.message)}); using the default prompt",
+          :yellow
+        @user_template = false
+        nil
+      end
+
+      def detail(stderr)
+        line = first_line(stderr)
+        line.empty? ? "" : ": #{line}"
+      end
+
+      def first_line(message)
+        message.to_s.lines.first.to_s.strip
+      end
+
+      def abs(path)
+        File.join(@root, path)
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/stack_profile.rb

@@ -147,7 +147,7 @@ module Rails
 
       def enabled_gems
         require "rails/hyperdrive/install_layout"
-        require "rails/hyperdrive/lock_file"
+        require "rails/hyperdrive/config_file"
         root =
           if @app_root
             @app_root.to_s
@@ -156,8 +156,8 @@ module Rails
           end
         return [] unless root
 
-        ::Rails::Hyperdrive::LockFile.load(
-          File.join(root, ::Rails::Hyperdrive::InstallLayout::LOCK_PATH)
+        ::Rails::Hyperdrive::ConfigFile.load(
+          File.join(root, ::Rails::Hyperdrive::InstallLayout::CONFIG_PATH)
         ).enabled_gems
       rescue StandardError
         []

data/lib/rails/hyperdrive/version.rb

@@ -1,5 +1,5 @@
 module Rails
   module Hyperdrive
-    VERSION = "0.8.0"
+    VERSION = "0.9.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-hyperdrive
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Bakaface
@@ -104,6 +104,7 @@ files:
 - lib/rails/hyperdrive/canonical_skill_render.rb
 - lib/rails/hyperdrive/claude_md_import.rb
 - lib/rails/hyperdrive/companion_discovery.rb
+- lib/rails/hyperdrive/config_file.rb
 - lib/rails/hyperdrive/console_executor.rb
 - lib/rails/hyperdrive/drift_verdict.rb
 - lib/rails/hyperdrive/eager_footprint.rb
@@ -118,9 +119,12 @@ files:
 - lib/rails/hyperdrive/lock_file.rb
 - lib/rails/hyperdrive/manifest_lint.rb
 - lib/rails/hyperdrive/mcp_server.rb
+- lib/rails/hyperdrive/resolve/prompt.md.erb
+- lib/rails/hyperdrive/resolve_prompt.rb
 - lib/rails/hyperdrive/resources/skill.rb
 - lib/rails/hyperdrive/resources/stack_profile.rb
 - lib/rails/hyperdrive/safety/rack_middleware.rb
+- lib/rails/hyperdrive/sidecar_resolver.rb
 - lib/rails/hyperdrive/skill_template.rb
 - lib/rails/hyperdrive/sql_safety.rb
 - lib/rails/hyperdrive/stack_profile.rb