hunk_review_changes 0.2.0

data/lib/hunk_review_changes/diff.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "rouge"
+require "diff/lcs"
+require "cgi"
+
+module HunkReviewChanges
+  # Parses a unified-diff hunk and renders it as an HTML table with line-number
+  # gutters. Two layers of highlighting:
+  #
+  #   * Rouge syntax highlighting on context lines and unpaired add/del lines. The
+  #     class-based HTML formatter emits <span class="k"> tokens whose colours come
+  #     from CSS (app.css), which is what lets the same markup render light or dark.
+  #   * Word-level diff on lines that were modified in place: a run of deletions
+  #     immediately followed by a run of additions is paired line-by-line, and the
+  #     changed words are wrapped in dw-del / dw-add spans so the eye lands on exactly
+  #     what moved.
+  module Diff
+    module_function
+
+    FORMATTER = Rouge::Formatters::HTML.new
+
+    # Metadata lines that carry no reviewable content; always dropped. None of these
+    # collide with an in-hunk content line, whose raw form always begins with +, -,
+    # or a space.
+    SKIP_PREFIXES = [
+      "diff --git", "index ", "new file", "deleted file",
+      "similarity", "rename ", "old mode", "new mode", "\\ No newline"
+    ].freeze
+
+    # File header markers that DO collide with content once the line marker is added:
+    # a deleted "-- x" reads "--- x" and an added "++ x" reads "+++ x". Drop them only
+    # outside a hunk, where they are genuinely headers.
+    FILE_HEADER_PREFIXES = ["--- ", "+++ "].freeze
+
+    # A single rendered diff line. :html is filled in lazily: word-diff for paired
+    # modifications, Rouge highlighting for everything else.
+    Row = Struct.new(:kind, :old_ln, :new_ln, :text, :html, keyword_init: true)
+
+    def to_html(diff_text, file)
+      rows = parse(diff_text)
+      pair_modifications!(rows)
+      lexer = lexer_for(file)
+      render(rows, lexer)
+    end
+
+    def parse(diff_text)
+      old_ln = new_ln = nil
+      in_hunk = false
+      rows = []
+      diff_text.to_s.each_line do |raw|
+        line = raw.chomp
+        if line.start_with?("@@")
+          old_ln, new_ln = hunk_bounds(line, old_ln, new_ln)
+          in_hunk = true
+          rows << Row.new(kind: :hunk, text: line)
+          next
+        end
+
+        # A new file section ends the current hunk, so its ---/+++ lines are headers.
+        in_hunk = false if line.start_with?("diff --git")
+        next if skip_metadata?(line, in_hunk)
+
+        old_ln, new_ln = push_content(rows, line, old_ln, new_ln)
+      end
+      rows
+    end
+
+    # Line numbers the next content line starts from, read off the @@ header.
+    def hunk_bounds(line, old_ln, new_ln)
+      return [old_ln, new_ln] unless (m = line.match(/@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/))
+
+      [m[1].to_i, m[2].to_i]
+    end
+
+    # File-metadata lines are dropped; the ---/+++ pair only outside a hunk, where it
+    # is a real header rather than an added/deleted line that happens to start with +/-.
+    def skip_metadata?(line, in_hunk)
+      return true if SKIP_PREFIXES.any? { |prefix| line.start_with?(prefix) }
+
+      !in_hunk && FILE_HEADER_PREFIXES.any? { |prefix| line.start_with?(prefix) }
+    end
+
+    # Append the add/del/context row for a content line and return the advanced
+    # [old_ln, new_ln] cursor (nil bounds stay nil).
+    def push_content(rows, line, old_ln, new_ln)
+      content = line.length > 1 ? line[1..] : ""
+      case line[0]
+      when "+"
+        rows << Row.new(kind: :add, new_ln: new_ln, text: content)
+        [old_ln, new_ln && (new_ln + 1)]
+      when "-"
+        rows << Row.new(kind: :del, old_ln: old_ln, text: content)
+        [old_ln && (old_ln + 1), new_ln]
+      else # context (space marker or blank line)
+        rows << Row.new(kind: :ctx, old_ln: old_ln, new_ln: new_ln, text: content)
+        [old_ln && (old_ln + 1), new_ln && (new_ln + 1)]
+      end
+    end
+
+    # Find each run of deletions followed immediately by a run of additions and pair
+    # them line-by-line, filling :html with word-level highlighting on both sides.
+    def pair_modifications!(rows)
+      index = 0
+      while index < rows.length
+        unless rows[index].kind == :del
+          index += 1
+          next
+        end
+
+        del_start = index
+        index += 1 while index < rows.length && rows[index].kind == :del
+        add_start = index
+        index += 1 while index < rows.length && rows[index].kind == :add
+
+        dels = rows[del_start...add_start]
+        adds = rows[add_start...index]
+        [dels.length, adds.length].min.times do |offset|
+          del_html, add_html = word_diff(dels[offset].text, adds[offset].text)
+          dels[offset].html = del_html
+          adds[offset].html = add_html
+        end
+      end
+    end
+
+    # Split a line into an alternating stream of identifiers, whitespace runs, and
+    # single punctuation characters so the word diff aligns on meaningful units.
+    def tokenize(text)
+      text.scan(/\w+|\s+|[^\w\s]/)
+    end
+
+    # Returns [del_html, add_html] with changed tokens wrapped in dw-del / dw-add.
+    def word_diff(old_text, new_text)
+      changes = ::Diff::LCS.sdiff(tokenize(old_text), tokenize(new_text))
+      del = +""
+      add = +""
+      changes.each do |change|
+        case change.action
+        when "=" # unchanged on both sides
+          del << esc(change.old_element)
+          add << esc(change.new_element)
+        when "-" # only in the old line
+          del << %(<span class="dw-del">#{esc(change.old_element)}</span>)
+        when "+" # only in the new line
+          add << %(<span class="dw-add">#{esc(change.new_element)}</span>)
+        when "!" # replaced
+          del << %(<span class="dw-del">#{esc(change.old_element)}</span>)
+          add << %(<span class="dw-add">#{esc(change.new_element)}</span>)
+        end
+      end
+      [del, add]
+    end
+
+    def render(rows, lexer)
+      out = +%(<table class="diff highlight">)
+      rows.each do |row|
+        out << render_row(row, lexer)
+      end
+      out << "</table>"
+      out
+    end
+
+    def render_row(row, lexer)
+      return %(<tr class="diff-hunk"><td colspan="3">#{esc(row.text)}</td></tr>) if row.kind == :hunk
+
+      sign =
+        case row.kind
+        when :add then "+"
+        when :del then "-"
+        else " "
+        end
+      code = row.html || highlight(lexer, row.text)
+      %(<tr class="diff-row diff-#{row.kind}">) <<
+        gutter(row.old_ln) <<
+        gutter(row.new_ln) <<
+        %(<td class="diff-code"><span class="diff-sign">#{sign}</span>#{code}</td></tr>)
+    end
+
+    def gutter(num)
+      %(<td class="diff-gutter">#{num}</td>)
+    end
+
+    def highlight(lexer, content)
+      return "" if content.empty?
+
+      FORMATTER.format(lexer.lex(content)).chomp
+    end
+
+    def lexer_for(file)
+      lexer =
+        begin
+          Rouge::Lexer.guess_by_filename(file.to_s)
+        rescue Rouge::Guesser::Ambiguous => e
+          e.alternatives.first
+        rescue StandardError
+          nil
+        end
+      (lexer || Rouge::Lexers::PlainText).new
+    end
+
+    def esc(str)
+      CGI.escapeHTML(str.to_s)
+    end
+  end
+end

data/lib/hunk_review_changes/export.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module HunkReviewChanges
+  # Builds export.md: the pieces that need action, as a paste-ready markdown block the
+  # launching agent reads to implement each requested change.
+  class Export
+    def initialize(bundle, state)
+      @bundle = bundle
+      @state = state
+    end
+
+    def to_markdown
+      lines = header
+      actionable = @bundle.pieces.select { |piece| State.actionable?(@state[piece["id"]]) }
+
+      if actionable.empty?
+        lines << no_changes_note
+        return "#{lines.join("\n").strip}\n"
+      end
+
+      lines << "The pieces below have comments to act on. Implement each `change`; " \
+               "list each `flag` for the user to decide before touching it."
+      lines << ""
+      actionable.each { |piece| lines.concat(piece_lines(piece)) }
+      "#{lines.join("\n").strip}\n"
+    end
+
+    private
+
+    # No piece needs action, but "reviewed and left as-is" and "never looked at" are
+    # different signals to the agent — the UI lets the user finish with pieces still
+    # unreviewed, and those must not read as approval.
+    def no_changes_note
+      unreviewed = @bundle.pieces.select { |piece| State.status_for(@state[piece["id"]]) == "unreviewed" }
+      return "_No changes requested — every piece was reviewed and left as-is._" if unreviewed.empty?
+
+      ids = unreviewed.map { |piece| piece["id"] }.join(", ")
+      "_No changes requested, but #{unreviewed.size} of #{@bundle.pieces.size} piece(s) were left " \
+        "unreviewed (skipped, not approved): #{ids}. Treat them as pending, not accepted._"
+    end
+
+    def header
+      lines = ["# Hunk review — #{@bundle.target}"]
+      lines << "Resolved by: #{@bundle.resolved_by}" if @bundle.resolved_by
+      lines << ""
+      lines << @bundle.framing.to_s.strip
+      lines << ""
+      lines
+    end
+
+    def piece_lines(piece)
+      entry = @state[piece["id"]]
+      status = State.status_for(entry)
+      comment = entry["comment"].to_s.strip
+      lines = [
+        "## Piece #{piece["id"]} of #{@bundle.pieces.size} — #{piece["file"]}: #{piece["label"]}",
+        "Status: #{status}",
+        "",
+        "```diff",
+        piece["diff"].to_s.rstrip,
+        "```",
+        "Comment: #{comment.empty? ? "—" : comment}"
+      ]
+      lines.concat(challenge_lines(piece["challenge"]))
+      lines << ""
+      lines
+    end
+
+    # The adversary's case travels with the comment so the implementing agent weighs
+    # both, rather than acting on the request without ever seeing the argument against
+    # it. A concession still earns its line: knowing the adversary looked and passed is
+    # different from it never having run.
+    def challenge_lines(challenge)
+      return [] unless challenge.is_a?(Hash)
+
+      stance = challenge["stance"].to_s
+      argument = challenge["argument"].to_s.strip
+      return ["Adversary (#{stance}): #{argument}"] unless stance == "concede"
+
+      note = argument.empty? ? nil : " (#{argument})"
+      ["Adversary: conceded — no objection#{note}"]
+    end
+  end
+end

data/lib/hunk_review_changes/installer/base.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module HunkReviewChanges
+  module Installer
+    # Common interface for a per-agent install adapter. An adapter knows how to detect
+    # its agent and how to register the skill for it — either by calling the agent's
+    # own CLI (Claude Code) or by copying the skill out of the marketplace checkout
+    # into the directory that agent scans (Codex, Cursor, OpenCode).
+    class Base
+      # Outcome of one adapter run, rendered in the install summary.
+      Result = Struct.new(:key, :label, :ok, :message, keyword_init: true)
+
+      def key = raise NotImplementedError
+      def label = raise NotImplementedError
+
+      # True when the agent is present on this machine (CLI on PATH or config dir).
+      def detected? = raise NotImplementedError
+
+      # Perform the install against a SkillSource; return a Result.
+      def install!(_source) = raise NotImplementedError
+
+      protected
+
+      def ok(message) = Result.new(key: key, label: label, ok: true, message: message)
+      def failure(message) = Result.new(key: key, label: label, ok: false, message: message)
+
+      def command_on_path?(name)
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |dir|
+          path = File.join(dir, name)
+          File.executable?(path) && !File.directory?(path)
+        end
+      end
+
+      def home(*parts)
+        File.join(Dir.home, *parts)
+      end
+    end
+  end
+end

data/lib/hunk_review_changes/installer/claude_code.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "open3"
+
+require_relative "base"
+
+module HunkReviewChanges
+  module Installer
+    # Claude Code is the one agent with a real, non-interactive plugin install CLI, so
+    # this adapter uses it: register the marketplace repo, then install the plugin from
+    # it. Skills inside the plugin are auto-discovered once it is installed.
+    class ClaudeCode < Base
+      def key = :claude
+      def label = "Claude Code"
+
+      def detected?
+        command_on_path?("claude") || File.directory?(home(".claude"))
+      end
+
+      def install!(source)
+        return failure("`claude` CLI not found on PATH") unless command_on_path?("claude")
+
+        added, add_out = run("claude", "plugin", "marketplace", "add", source.repo)
+        return failure("`claude plugin marketplace add` failed: #{add_out}") unless added
+
+        installed, install_out = run(
+          "claude", "plugin", "install", "#{PLUGIN_NAME}@#{MARKETPLACE_NAME}"
+        )
+        return failure("`claude plugin install` failed: #{install_out}") unless installed
+
+        ok("installed plugin #{PLUGIN_NAME}@#{MARKETPLACE_NAME} (user scope)")
+      end
+
+      private
+
+      def run(*command)
+        out, status = Open3.capture2e(*command)
+        [status.success?, out.strip]
+      rescue StandardError => e
+        [false, e.message]
+      end
+    end
+  end
+end

data/lib/hunk_review_changes/installer/codex.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "directory_installer"
+
+module HunkReviewChanges
+  module Installer
+    # Codex reads user-level skills from the shared, tool-agnostic ~/.agents/skills.
+    class Codex < DirectoryInstaller
+      def key = :codex
+      def label = "Codex"
+
+      def detected?
+        command_on_path?("codex") || File.directory?(home(".codex")) || File.directory?(home(".agents"))
+      end
+
+      def skills_root
+        home(".agents", "skills")
+      end
+    end
+  end
+end

data/lib/hunk_review_changes/installer/cursor.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "directory_installer"
+
+module HunkReviewChanges
+  module Installer
+    # Cursor reads user-level skills from ~/.cursor/skills.
+    class Cursor < DirectoryInstaller
+      def key = :cursor
+      def label = "Cursor"
+
+      def detected?
+        command_on_path?("cursor-agent") || command_on_path?("cursor") ||
+          File.directory?(home(".cursor"))
+      end
+
+      def skills_root
+        home(".cursor", "skills")
+      end
+    end
+  end
+end

data/lib/hunk_review_changes/installer/directory_installer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+require_relative "base"
+
+module HunkReviewChanges
+  module Installer
+    # Base for agents that have no install CLI (Codex, Cursor, OpenCode). They all scan
+    # a skills directory for `<name>/SKILL.md`, so installing means copying the skill
+    # out of the marketplace checkout into that directory. Subclasses supply the
+    # directory and how the agent is detected.
+    class DirectoryInstaller < Base
+      # Absolute path to the agent's user-level skills directory.
+      def skills_root = raise NotImplementedError
+
+      def install!(source)
+        target = File.join(skills_root, SKILL_NAME)
+        FileUtils.mkdir_p(target)
+        FileUtils.cp_r(File.join(source.skill_dir, "."), target)
+        ok("copied skill to #{pretty(target)} (restart #{label} to pick it up)")
+      rescue SkillSource::Error => e
+        failure(e.message)
+      rescue StandardError => e
+        failure("could not copy skill: #{e.message}")
+      end
+
+      private
+
+      def pretty(path)
+        home = Dir.home
+        path.start_with?(home) ? path.sub(home, "~") : path
+      end
+    end
+  end
+end

data/lib/hunk_review_changes/installer/opencode.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "directory_installer"
+
+module HunkReviewChanges
+  module Installer
+    # OpenCode reads user-level skills from ~/.config/opencode/skills.
+    class OpenCode < DirectoryInstaller
+      def key = :opencode
+      def label = "OpenCode"
+
+      def detected?
+        command_on_path?("opencode") || File.directory?(config_dir)
+      end
+
+      def skills_root
+        File.join(config_dir, "skills")
+      end
+
+      private
+
+      def config_dir
+        File.join(ENV.fetch("XDG_CONFIG_HOME", home(".config")), "opencode")
+      end
+    end
+  end
+end

data/lib/hunk_review_changes/installer/runner.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative "skill_source"
+require_relative "claude_code"
+require_relative "codex"
+require_relative "cursor"
+require_relative "opencode"
+
+module HunkReviewChanges
+  module Installer
+    # Drives the `install` command: detect which agents are present, let the user pick
+    # (or take an explicit list), install the skill into each, and print a summary.
+    class Runner
+      ADAPTERS = [ClaudeCode, Codex, Cursor, OpenCode].freeze
+
+      # Accepts agent keys plus a few friendly aliases from --agent.
+      ALIASES = {
+        "claude-code" => :claude, "claudecode" => :claude,
+        "cursor-agent" => :cursor, "open-code" => :opencode
+      }.freeze
+
+      def initialize(repo: MARKETPLACE_REPO, only: nil, input: $stdin, output: $stdout)
+        @source = SkillSource.new(repo)
+        @only = only
+        @input = input
+        @output = output
+        @adapters = ADAPTERS.map(&:new)
+      end
+
+      def run
+        if @only
+          ensure_known!(@only)
+          selected = by_keys(@only)
+        else
+          selected = prompt
+        end
+        if selected.empty?
+          @output.puts "Nothing selected — no changes made."
+          return []
+        end
+
+        @output.puts "\nInstalling from #{@source.repo}"
+        results = selected.map do |adapter|
+          @output.puts "  → #{adapter.label}…"
+          adapter.install!(@source)
+        end
+        report(results)
+        results
+      end
+
+      private
+
+      # An explicit --agent list naming an unknown agent must fail loudly: otherwise
+      # it selects nothing, "installs" nothing, and still exits 0 as if it worked.
+      def ensure_known!(keys)
+        known = @adapters.map(&:key)
+        unknown = Array(keys).flat_map { |k| expand(k) }.uniq - known
+        return if unknown.empty?
+
+        raise CLI::Error, "unknown agent#{"s" if unknown.size > 1}: #{unknown.join(", ")}. " \
+                          "Valid agents: #{known.join(", ")} (or 'all')."
+      end
+
+      def by_keys(keys)
+        wanted = Array(keys).flat_map { |k| expand(k) }.uniq
+        @adapters.select { |adapter| wanted.include?(adapter.key) }
+      end
+
+      def expand(key)
+        normalized = key.to_s.strip.downcase
+        return @adapters.map(&:key) if %w[all every].include?(normalized)
+
+        [ALIASES.fetch(normalized, normalized.to_sym)]
+      end
+
+      def prompt
+        @output.puts "Install the hunk-review-changes skill for which agents?\n\n"
+        @adapters.each_with_index do |adapter, index|
+          mark = adapter.detected? ? "detected" : "not detected"
+          @output.puts "  #{index + 1}. #{adapter.label} (#{mark})"
+        end
+        detected = @adapters.each_index.select { |i| @adapters[i].detected? }
+        default = detected.empty? ? "none" : detected.map { |i| i + 1 }.join(",")
+        @output.print "\nEnter numbers (comma-separated), 'all', or Enter for detected [#{default}]: "
+
+        answer = read_line
+        resolve_selection(answer, detected)
+      end
+
+      def resolve_selection(answer, detected)
+        answer = answer.to_s.strip.downcase
+        return @adapters if answer == "all"
+        return detected.map { |i| @adapters[i] } if answer.empty?
+
+        indexes = answer.split(/[,\s]+/).filter_map do |token|
+          num = Integer(token, exception: false)
+          num - 1 if num&.between?(1, @adapters.length)
+        end
+        indexes.uniq.map { |i| @adapters[i] }
+      end
+
+      def read_line
+        @input.gets
+      rescue StandardError
+        nil
+      end
+
+      def report(results)
+        @output.puts "\nSummary:"
+        results.each do |result|
+          icon = result.ok ? "✓" : "✗"
+          @output.puts "  #{icon} #{result.label}: #{result.message}"
+        end
+        failures = results.reject(&:ok)
+        return if failures.empty?
+
+        @output.puts "\n#{failures.length} of #{results.length} did not complete. " \
+                     "See messages above."
+      end
+    end
+  end
+end

data/lib/hunk_review_changes/installer/skill_source.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+
+module HunkReviewChanges
+  module Installer
+    # Provides a local checkout of the marketplace repo so adapters can read the skill
+    # from it. The marketplace repo is the single source of truth for the skill across
+    # agents; the gem never ships its own copy. A local path is used as-is (handy for
+    # testing); a remote URL is shallow-cloned to a temp dir on first use.
+    class SkillSource
+      class Error < StandardError
+      end
+
+      attr_reader :repo
+
+      def initialize(repo)
+        @repo = repo
+      end
+
+      def local?
+        File.directory?(@repo)
+      end
+
+      # Path to a local checkout of the marketplace repo.
+      def checkout
+        @checkout ||= local? ? File.expand_path(@repo) : clone
+      end
+
+      # Directory holding the skill (SKILL.md and any support files) in the checkout.
+      def skill_dir
+        dir = File.join(checkout, "plugins", PLUGIN_NAME, "skills", SKILL_NAME)
+        unless File.exist?(File.join(dir, "SKILL.md"))
+          raise Error, "no SKILL.md at #{dir} — is #{@repo} the marketplace repo?"
+        end
+
+        dir
+      end
+
+      private
+
+      def clone
+        target = Dir.mktmpdir("hunk-review-changes-skill-")
+        ok = system("git", "clone", "--depth", "1", @repo, target,
+                    out: File::NULL, err: File::NULL)
+        raise Error, "could not clone #{@repo} (is git installed and the URL reachable?)" unless ok
+
+        target
+      end
+    end
+  end
+end