rails-hyperdrive 0.3.0

data/lib/rails/hyperdrive/install_pipeline.rb

@@ -0,0 +1,415 @@
+require "time"
+require "rails/hyperdrive/audit_header"
+require "rails/hyperdrive/bundler_artifact_discovery"
+require "rails/hyperdrive/claude_md_import"
+require "rails/hyperdrive/drift_verdict"
+require "rails/hyperdrive/eager_footprint"
+require "rails/hyperdrive/index_document"
+require "rails/hyperdrive/install_layout"
+require "rails/hyperdrive/install_plan"
+require "rails/hyperdrive/lock_file"
+
+module Rails
+  module Hyperdrive
+    # The application root is explicit and no Rails constant is touched, so any
+    # process that can see the bundle can run this.
+    class InstallPipeline
+      ARTIFACT_DESTINATIONS =
+        [InstallLayout::SKILLS_DIR, InstallLayout::HYPERDRIVE_DIR, InstallLayout::LOCK_PATH].freeze
+
+      WARN_LINES = 150
+      WARN_TOKENS = 1_500
+
+      MODES = %i[preserve overwrite additive].freeze
+
+      Result = Struct.new(:installed, :updated, :unchanged, :skipped, :orphaned, :removed, keyword_init: true)
+
+      def initialize(root:, shell:, artifacts:, mode: :preserve, warnings: [])
+        raise ArgumentError, "unknown mode #{mode.inspect}" unless MODES.include?(mode)
+
+        @root = File.expand_path(root.to_s)
+        @shell = shell
+        @artifacts = artifacts
+        @mode = mode
+        @warnings = warnings
+        @result = Result.new(installed: [], updated: [], unchanged: [], skipped: [], orphaned: [], removed: [])
+      end
+
+      def call
+        @new_lock = LockFile.new(abs(InstallLayout::LOCK_PATH)).carry_settings(old_lock)
+        @plan = plan
+
+        report_collisions
+        report_disabled
+        install_skills
+        guidelines = install_guidelines
+        remove_disabled
+        remove_stale_support_files
+        carry_orphans
+        eager_guidelines = write_index_md(guidelines)
+        write_claude_md(guidelines)
+        write_lock
+        print_warnings
+        print_footprint(guidelines: eager_guidelines)
+        warn_if_destinations_gitignored
+        @result
+      end
+
+      def plan
+        build_result.entries
+      end
+
+      def lock
+        @new_lock
+      end
+
+      private
+
+      def build_result
+        @build_result ||= InstallPlan.build(@artifacts, lock: old_lock)
+      end
+
+      def old_lock
+        @old_lock ||= LockFile.load(abs(InstallLayout::LOCK_PATH))
+      end
+
+      def additive?
+        @mode == :additive
+      end
+
+      def overwrite_mode?
+        @mode == :overwrite
+      end
+
+      def abs(path)
+        File.join(@root, path)
+      end
+
+      def report_collisions
+        @plan.group_by { |e| [e.type, e.artifact.name] }.each do |(type, name), group|
+          next unless group.first.collision
+          @shell.say_status :conflict,
+            "#{type} '#{name}' shipped by #{group.map { |e| e.artifact.source_gem }.join(", ")}; installing all (postfixed)",
+            :yellow
+        end
+      end
+
+      def report_disabled
+        build_result.disabled.each do |entry|
+          @shell.say_status :disabled, "#{entry.type} '#{entry.final_name}' (listed in #{InstallLayout::LOCK_PATH})", :blue
+        end
+      end
+
+      def install_skills
+        @plan.select { |e| e.type == :skill }.each do |entry|
+          install_file(entry: entry, type: :skill, install_ready_body: entry.install_ready_body)
+          entry.support_files.each do |file|
+            install_file(
+              dest: file[:dest],
+              type: :skill_support,
+              install_ready_body: file[:body],
+              source_gem: entry.source_gem,
+              version: entry.version,
+              artifact_kind: "skill_support"
+            )
+          end
+        end
+      end
+
+      def install_guidelines
+        @plan.select { |e| e.type == :guideline }.map do |entry|
+          body = entry.install_ready_body
+          warn_if_oversize(entry.dest, body)
+          install_file(entry: entry, type: :guideline, install_ready_body: body)
+          { base: "#{entry.final_name}.md", dest: entry.dest, body: body }
+        end
+      end
+
+      def install_file(dest: nil, type:, install_ready_body:, entry: nil, source_gem: nil, version: nil, artifact_kind: nil)
+        write = {
+          dest: dest || entry.dest,
+          type: type,
+          body: install_ready_body,
+          source_gem: source_gem || entry.source_gem,
+          version: version || entry.version,
+          gem_sha: DriftVerdict.body_sha(install_ready_body),
+          artifact_kind: artifact_kind || entry.artifact_kind
+        }
+        old = old_lock.entry(write[:dest])
+
+        return additive_install(write, old) if additive?
+
+        file = abs(write[:dest])
+        case DriftVerdict.verdict(file: file, kind: write[:artifact_kind], lock_entry: old, gem_sha: write[:gem_sha])
+        when :missing
+          @shell.say_status(:reinstall, "#{write[:dest]} (was missing)", :yellow) if old
+          write_artifact(**write)
+        when :current
+          @new_lock.carry(old)
+          @result.unchanged << write[:dest]
+          @shell.say_status :unchanged, write[:dest], :blue
+        when :outdated
+          write_artifact(**write)
+        when :edited
+          if overwrite_mode?
+            write_artifact(**write)
+          else
+            @result.skipped << write[:dest]
+            @shell.say_status :skip, "#{write[:dest]} (locally modified; run hyperdrive:sync --overwrite to overwrite)", :yellow
+            @new_lock.carry(old) if old
+          end
+        end
+      end
+
+      # Additive installs can create a file and never overwrite one, so an
+      # artifact the user edited — or deleted on purpose — survives.
+      def additive_install(write, old)
+        if old
+          @new_lock.carry(old)
+          (old.source_sha == write[:gem_sha] ? @result.unchanged : @result.skipped) << write[:dest]
+        elsif File.exist?(abs(write[:dest]))
+          @result.skipped << write[:dest]
+        else
+          write_artifact(**write)
+        end
+      end
+
+      # Supporting files land byte-identical to what the gem ships — no audit
+      # header, since they may be non-markdown or binary; provenance and sha
+      # live in the lock alone.
+      def write_artifact(dest:, type:, body:, source_gem:, version:, gem_sha:, artifact_kind:)
+        installed_at = Time.now.utc
+        header_args = { source_gem: source_gem, version: version, sha256: gem_sha, installed_at: installed_at }
+        on_disk =
+          case type
+          when :skill
+            AuditHeader.inject_into_frontmatter(body, AuditHeader.build(**header_args))
+          when :skill_support
+            body
+          else
+            AuditHeader.prepend_html(body, AuditHeader.build_html(**header_args))
+          end
+
+        existed = old_lock.entry(dest)
+        @shell.create_file dest, on_disk
+        (existed ? @result.updated : @result.installed) << dest
+        @new_lock.upsert(
+          path: dest,
+          kind: artifact_kind,
+          source_gem: source_gem,
+          source_version: version,
+          source_sha: gem_sha,
+          installed_at: installed_at.iso8601
+        )
+      end
+
+      # The pipeline's only delete path, so it is gated on the file still
+      # matching the content the lock recorded: hand-edited work is reported and
+      # left for its owner to remove. Runs before orphans are carried, or a
+      # removed file would read as one.
+      def remove_disabled
+        return if additive?
+
+        old_lock.each_entry do |entry|
+          type = InstallLayout::ARTIFACT_TYPES[entry.kind]
+          next unless type
+          next if @new_lock.entry(entry.path)
+
+          next unless InstallPlan.disabled_dest?(old_lock, type, entry.path)
+
+          file = abs(entry.path)
+          next unless File.exist?(file)
+
+          if DriftVerdict.unedited?(file, lock_entry: entry)
+            @shell.remove_file entry.path
+            @result.removed << entry.path
+            prune_empty_dirs(entry.path)
+          else
+            @result.skipped << entry.path
+            @shell.say_status :skip,
+              "#{entry.path} (disabled but locally modified; delete it by hand)", :yellow
+            @new_lock.carry(entry)
+          end
+        end
+      end
+
+      # Deletion is gated on the recorded sha, so a user-edited copy is never
+      # removed.
+      def remove_stale_support_files
+        return if additive?
+
+        planned_skill_dirs = @plan.select { |e| e.type == :skill }.map { |e| File.dirname(e.dest) }
+
+        old_lock.each_entry do |entry|
+          next unless entry.kind == "skill_support"
+          next if @new_lock.entry(entry.path)
+          next unless planned_skill_dirs.include?(InstallLayout.skill_dir_of(entry.path))
+
+          file = abs(entry.path)
+          next unless File.exist?(file)
+
+          if DriftVerdict.unedited?(file, lock_entry: entry)
+            @shell.remove_file entry.path
+            @result.removed << entry.path
+            prune_empty_dirs(entry.path)
+          else
+            @result.skipped << entry.path
+            @shell.say_status :skip,
+              "#{entry.path} (no longer shipped by #{entry.source_label} but locally modified; delete it by hand)",
+              :yellow
+            @new_lock.carry(entry)
+          end
+        end
+      end
+
+      # Skill directories go only once empty; any user file keeps the whole
+      # chain alive. The just-removed entry is subtracted because a dry run
+      # deletes nothing from disk.
+      def prune_empty_dirs(removed_dest)
+        removed = abs(removed_dest)
+        dir = File.dirname(removed_dest)
+        while dir.start_with?("#{InstallLayout::SKILLS_DIR}/")
+          children = Dir.exist?(abs(dir)) ? Dir.children(abs(dir)).map { |c| File.join(abs(dir), c) } : []
+          children -= [removed]
+          break unless children.empty?
+
+          @shell.remove_file dir
+          removed = abs(dir)
+          dir = File.dirname(dir)
+        end
+      end
+
+      def carry_orphans
+        planned = @plan.map(&:dest)
+        old_lock.each_entry do |entry|
+          next if planned.include?(entry.path)
+          next if @new_lock.entry(entry.path)
+          next unless DriftVerdict.verdict(file: abs(entry.path), kind: entry.kind, lock_entry: entry, gem_sha: nil) == :orphaned
+
+          @result.orphaned << entry.path
+          @shell.say_status :orphan,
+            "#{entry.path} (source #{entry.source_label} no longer in bundle; left in place)", :yellow
+          @new_lock.carry(entry)
+        end
+      end
+
+      # Returns the eager set: the guidelines index.md ends up including.
+      def write_index_md(guidelines)
+        return amend_index_md(guidelines) if additive?
+        return teardown_index_md if guidelines.empty?
+
+        existing = read_index
+        rendered = IndexDocument.render(
+          guidelines: guidelines,
+          existing: existing,
+          previously_installed: old_lock.guideline_paths.map { |p| File.basename(p) }
+        )
+
+        if existing == rendered.content
+          @shell.say_status :unchanged, InstallLayout::INDEX_PATH, :blue
+        else
+          @shell.create_file InstallLayout::INDEX_PATH, rendered.content
+        end
+        rendered.guidelines
+      end
+
+      def amend_index_md(guidelines)
+        added = guidelines.select { |g| @result.installed.include?(g[:dest]) }.map { |g| g[:base] }
+        content = IndexDocument.amend(existing: read_index, added: added)
+        @shell.create_file InstallLayout::INDEX_PATH, content if content
+        [] # an additive run prints no footprint, so it reports no eager set
+      end
+
+      # No sha gate: the file has no lock entry, and the only user input it
+      # carries is a deleted `@`-line, which is moot once no guideline is
+      # planned.
+      def teardown_index_md
+        if File.exist?(abs(InstallLayout::INDEX_PATH))
+          @shell.remove_file InstallLayout::INDEX_PATH
+          @result.removed << InstallLayout::INDEX_PATH
+        end
+        []
+      end
+
+      def read_index
+        file = abs(InstallLayout::INDEX_PATH)
+        File.read(file) if File.exist?(file)
+      end
+
+      def write_claude_md(guidelines)
+        file = abs(ClaudeMdImport::PATH)
+        content = File.read(file) if File.exist?(file)
+        decision =
+          if guidelines.empty? && !additive?
+            ClaudeMdImport.teardown(content: content, state: old_lock.claude_md_state)
+          else
+            ClaudeMdImport.decide(content: content, state: old_lock.claude_md_state, mode: @mode)
+          end
+
+        case decision.action
+        when :create  then @shell.create_file ClaudeMdImport::PATH, decision.body
+        when :append  then @shell.append_to_file ClaudeMdImport::PATH, decision.body
+        when :rewrite then @shell.create_file ClaudeMdImport::PATH, decision.body
+        when :delete  then @shell.remove_file ClaudeMdImport::PATH
+        end
+        @shell.say_status :warn, decision.warning, :yellow if decision.warning
+
+        @new_lock.claude_md_state = decision.state
+      end
+
+      def write_lock
+        @shell.create_file InstallLayout::LOCK_PATH, @new_lock.to_yaml
+      end
+
+      def print_warnings
+        return if Array(@warnings).empty?
+        @shell.say ""
+        @shell.say_status :warn, "discovery skipped #{@warnings.size} artifact(s):", :yellow
+        @warnings.each { |w| @shell.say "    - #{w}" }
+      end
+
+      def print_footprint(guidelines:)
+        return if additive?
+
+        EagerFootprint.lines(guidelines: guidelines).each do |line|
+          @shell.say_status line.status, line.message, line.color
+        end
+      end
+
+      def warn_if_destinations_gitignored
+        # An additive run has no terminal to warn at; it reports through its result.
+        return if additive?
+        ignored = gitignored_destinations
+        return if ignored.empty?
+
+        @shell.say_status :warn,
+          "#{ignored.join(", ")} #{ignored.one? ? "is" : "are"} gitignored; installed artifacts stay out of " \
+          "git status and pull-request diffs, so companion-shipped content reaches the agent unreviewed",
+          :yellow
+      end
+
+      # Patterns, negations, and per-repository excludes all decide ignore
+      # status, so git is the only correct oracle. Fail-open: no match, no
+      # repository, and no git alike exit non-zero and read as "not ignored".
+      def gitignored_destinations
+        output = IO.popen(
+          ["git", "check-ignore", "--", *ARTIFACT_DESTINATIONS],
+          chdir: @root, err: File::NULL, &:read
+        )
+        return [] unless $?&.success?
+        output.to_s.split("\n").map(&:strip).reject(&:empty?)
+      rescue SystemCallError
+        []
+      end
+
+      def warn_if_oversize(dest, body)
+        lines = body.lines.size
+        tokens = EagerFootprint.approx_tokens(body)
+        return unless lines > WARN_LINES || tokens > WARN_TOKENS
+        @shell.say_status :warn,
+          "#{dest} is large (#{lines} lines, ~#{tokens} tokens); guidelines are eager — move tutorial content to a skill",
+          :yellow
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/install_plan.rb

@@ -0,0 +1,78 @@
+require "rails/hyperdrive/bundler_artifact_discovery"
+require "rails/hyperdrive/install_layout"
+
+module Rails
+  module Hyperdrive
+    # A name shipped by one source installs at its canonical path; a name
+    # shipped by several installs every variant, postfixed --<source_gem>.
+    module InstallPlan
+      Entry = Struct.new(:type, :artifact, :final_name, :dest, :collision, keyword_init: true) do
+        # The renamed name: is part of the hashed body, so a postfixed skill
+        # hashes to a stable value.
+        def install_ready_body
+          body = BundlerArtifactDiscovery.install_ready_body(artifact)
+          return body unless type == :skill && final_name != artifact.name
+          body.sub(/^name:\s*.+$/, "name: #{final_name}")
+        end
+
+        def support_files
+          return [] unless type == :skill
+          dir = File.dirname(dest)
+          Array(artifact.support_files).map do |file|
+            { path: file[:path], body: file[:body], dest: "#{dir}/#{file[:path]}" }
+          end
+        end
+
+        def source_gem
+          artifact.source_gem
+        end
+
+        def version
+          artifact.spec_version
+        end
+
+        def source_label
+          "#{source_gem}@#{version}"
+        end
+
+        def artifact_kind
+          type.to_s
+        end
+      end
+
+      Result = Struct.new(:entries, :disabled, keyword_init: true)
+
+      module_function
+
+      # A collision installs under a postfixed name, so the shipped name
+      # disables every variant and a postfixed name disables just one.
+      def build(artifacts, lock: nil)
+        result = Result.new(entries: [], disabled: [])
+        artifacts.group_by { |a| [a.artifact_type, a.name] }.each do |(type, name), group|
+          collision = group.size > 1
+          group.each do |artifact|
+            final_name = collision ? InstallLayout.postfixed_name(name, artifact.source_gem) : name
+            entry = Entry.new(
+              type: type,
+              artifact: artifact,
+              final_name: final_name,
+              dest: InstallLayout.dest_for(type, final_name),
+              collision: collision
+            )
+            dropped = lock && (lock.disabled?(type, name) || (collision && lock.disabled?(type, final_name)))
+            (dropped ? result.disabled : result.entries) << entry
+          end
+        end
+        result
+      end
+
+      # A supporting file is disabled through its owning skill's name.
+      def disabled_dest?(lock, type, dest)
+        name = InstallLayout.installed_name(type, dest)
+        return false unless name
+        lookup = type == :skill_support ? :skill : type
+        lock.disabled?(lookup, name) || lock.disabled?(lookup, InstallLayout.base_name(name))
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/install_shell.rb

@@ -0,0 +1,43 @@
+require "fileutils"
+
+module Rails
+  module Hyperdrive
+    class InstallShell
+      attr_reader :root
+
+      def initialize(root:, io: nil, pretend: false)
+        @root = File.expand_path(root.to_s)
+        @io = io
+        @pretend = pretend
+      end
+
+      def create_file(path, content)
+        abs = File.join(@root, path)
+        unless @pretend
+          FileUtils.mkdir_p(File.dirname(abs))
+          File.write(abs, content)
+        end
+        say_status(:create, path)
+      end
+
+      def remove_file(path)
+        FileUtils.rm_rf(File.join(@root, path)) unless @pretend
+        say_status(:remove, path)
+      end
+
+      def append_to_file(path, content)
+        abs = File.join(@root, path)
+        File.open(abs, "a") { |f| f.write(content) } unless @pretend
+        say_status(:append, path)
+      end
+
+      def say_status(kind, message, _color = nil)
+        @io&.puts(format("%12s  %s", kind, message))
+      end
+
+      def say(message = "")
+        @io&.puts(message)
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/lock_file.rb

@@ -0,0 +1,171 @@
+require "yaml"
+
+module Rails
+  module Hyperdrive
+    # installed_at is volatile metadata, never an input to any comparison.
+    class LockFile
+      SCHEMA_VERSION = 1
+      STATE_PRESENT  = "present".freeze
+      STATE_REMOVED  = "removed-by-user".freeze
+
+      DISABLED_KEYS = { skill: "skills", guideline: "guidelines" }.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
+        def source_label
+          source_version ? "#{source_gem}@#{source_version}" : source_gem
+        end
+      end
+
+      attr_reader :path
+      attr_accessor :claude_md_state
+
+      # Load existing lock state from disk (absent file → empty lock).
+      def self.load(path)
+        new(path).tap(&:read)
+      end
+
+      def initialize(path)
+        @path = path.to_s
+        @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
+      end
+
+      def read
+        return self unless File.exist?(@path)
+
+        data = YAML.safe_load(File.read(@path))
+        return self unless data.is_a?(Hash)
+
+        @document = data
+        claude_md = data["claude_md"]
+        @claude_md_state = claude_md["state"] if claude_md.is_a?(Hash)
+        @disabled = parse_disabled(data["disabled"])
+        Array(data["files"]).each do |raw|
+          next unless raw.is_a?(Hash)
+          entry = build_entry(raw)
+          @files[entry.path] = entry if entry.path
+        end
+        self
+      rescue Psych::SyntaxError
+        self
+      end
+
+      def entry(file_path)
+        @files[file_path.to_s]
+      end
+
+      def guideline_paths
+        @files.values.select { |e| e.kind == "guideline" }.map(&:path)
+      end
+
+      def each_entry(&block)
+        @files.values.each(&block)
+      end
+
+      def disabled?(type, name)
+        Array(@disabled[type.to_sym]).include?(name.to_s)
+      end
+
+      # Adopt the state that is not derived from installed content, so
+      # rewriting the file preserves it.
+      def carry_settings(other)
+        @document = other.document.dup
+        @disabled = other.disabled_lists.dup
+        self
+      end
+
+      def upsert(path:, kind:, source_gem:, source_version:, source_sha:, installed_at:)
+        @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
+        )
+      end
+
+      def carry(entry)
+        return unless entry && entry.path
+        @files[entry.path] = entry
+      end
+
+      def to_yaml
+        carried = @document["claude_md"]
+        carried = {} unless carried.is_a?(Hash)
+
+        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] },
+          "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?
+        document.to_yaml
+      end
+
+      protected
+
+      def document
+        @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 build_entry(raw)
+        source_gem, source_version = split_source(raw["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"]
+        )
+      end
+
+      # A source with no "@" (hand-edited) keeps its whole value as the gem
+      # part with a nil version, so serialization re-emits it unchanged.
+      def split_source(source)
+        return [nil, nil] if source.nil?
+        source = source.to_s
+        idx = source.index("@")
+        idx ? [source[0...idx], source[(idx + 1)..]] : [source, nil]
+      end
+
+      def serialize_entry(entry)
+        {
+          "path"         => entry.path,
+          "artifact"     => entry.kind,
+          "source"       => entry.source_label,
+          "source_sha"   => entry.source_sha,
+          "installed_at" => entry.installed_at
+        }
+      end
+    end
+  end
+end