hunk_review_changes 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f6091eebcab16183733cb278161b9d3087150f938521ab7b281e7418cf2a96bc
+  data.tar.gz: 707a53f52a4cb6b0aa347d2526a3fc87ea525eedd61a54ce67b533e50078530e
+SHA512:
+  metadata.gz: 125e911c129ac684d690d6a44e1f9de6bd0c9355cbb8a188cef9e93204cc1d66ecad2cc1dbd13cdb449442dd0baeed3a21cc74748846f92f8334c0de563144b2
+  data.tar.gz: 139a39da05e7972c9c32f63cbd6cc50bf65b4746e57ce6ded335b113a068dac557e188d8f7316b045da841f5a85425eeb4fda2ccddd9d52b34d70c76e9278361

data/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 0.2.0 (2026-08-03)
+
+- Battle review: a bundle piece may now carry a `challenge` — an adversary's argument
+  against the change — and the bundle a top-level `adversary` naming who made it. The
+  viewer renders the challenge as its own voice, distinct from the author's what/why,
+  with a stance badge (`nitpick`, `concern`, `blocking`); a `concede` stance renders as
+  a quiet "no objection" line so you know the adversary looked.
+- `export.md` carries the challenge for every piece you comment on or flag, so the agent
+  implementing your comment also sees the argument against it.
+- Both fields are optional. A bundle written without them renders and exports exactly as
+  before.
+
+## 0.1.0 (2026-07-20)
+
+- First release as a gem. Packages the browser review UI, all Ruby code, prebuilt CSS,
+  and the bundled Atkinson Hyperlegible fonts.
+- `hunk-review-changes <bundle.json>` serves the review UI; `--port` and `--no-open`
+  flags supported.
+- `hunk-review-changes install` installs the companion skill into Claude Code (via its
+  plugin marketplace CLI) and Codex, Cursor, and OpenCode (by copying the skill into
+  the directory each scans).
+- UI overhaul: Atkinson Hyperlegible Next / Mono fonts, wider layout with 120-column
+  diffs, dark mode that follows the OS setting, word-level diff highlighting, an
+  explicit per-hunk "Looks good" reviewed state, and `j`/`k`/`c`/`g`/`?` keyboard
+  navigation.
+- Bundles are validated on launch with actionable error messages.
+- Fix comment loss on exit: a comment typed within the 500ms autosave window is now
+  flushed before Done writes the export, and persisted with `navigator.sendBeacon`
+  when the tab is closed.
+- Open the browser on Linux and Windows too (`xdg-open` / `start`), not just macOS,
+  and warn with the review URL instead of failing silently when no browser launches.

data/LICENSE.txt

@@ -0,0 +1,27 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Lucian Ghinda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+---
+
+The bundled fonts in lib/hunk_review_changes/public/fonts (Atkinson Hyperlegible
+Next and Atkinson Hyperlegible Mono) are licensed under the SIL Open Font License,
+Version 1.1. See lib/hunk_review_changes/public/fonts/OFL.txt for the full text.

data/README.md

@@ -0,0 +1,126 @@
+# hunk_review_changes
+
+Review a diff hunk-by-hunk in your browser, then hand the comments back to your AI coding agent.
+
+Your agent groups a diff into pieces — each a hunk with a plain-language what/why — and launches a local web app. You read the highlighted hunks and comment on each at your own pace. No model tokens are spent while you review. Click **Done** and the agent picks up your comments and implements them.
+
+Works with Claude Code, Codex, Cursor, and OpenCode.
+
+[![CI](https://github.com/lucianghinda/hunk-review-changes/actions/workflows/ci.yml/badge.svg)](https://github.com/lucianghinda/hunk-review-changes/actions/workflows/ci.yml)
+
+## Installation
+
+Install the gem:
+
+```sh
+gem install hunk_review_changes
+```
+
+Then install the companion skill into your agents:
+
+```sh
+hunk-review-changes install
+```
+
+It asks which agents to set up and installs the skill for each.
+
+## How it works
+
+1. You ask your agent to review a change — a branch, PR, commit, or your working tree.
+2. The skill resolves the target, groups it into hunks, and writes a `bundle.json`.
+3. It runs `hunk-review-changes bundle.json`, which opens the review UI in your browser.
+4. For each hunk you leave a comment, mark it **Looks good**, or **Flag for discussion**.
+5. You click **Done**. The app writes `export.md` and exits.
+6. Your agent reads the export and implements every requested change.
+
+## Usage
+
+Serve a bundle:
+
+```sh
+hunk-review-changes bundle.json
+```
+
+Options:
+
+```sh
+hunk-review-changes bundle.json --port 4321   # bind a specific port
+hunk-review-changes bundle.json --no-open      # do not open the browser
+```
+
+Install the skill for specific agents without the prompt:
+
+```sh
+hunk-review-changes install --agent claude,codex,cursor,opencode
+```
+
+## The review UI
+
+- **120-column diffs** with syntax highlighting, in [Atkinson Hyperlegible](https://www.brailleinstitute.org/freefont/) fonts.
+- **Word-level highlighting** shows exactly what changed within a modified line.
+- **Dark mode** follows your operating system setting.
+- **Keyboard navigation** — `j`/`k` to move between hunks, `c` to comment, `g` to mark Looks good, `?` for help.
+- **Reviewed state** — every hunk tracks whether you have seen it, so you know what is left.
+
+Your review persists as you go, so closing the tab loses nothing. Re-running the same bundle resumes it.
+
+## Battle review
+
+Every explanation on a hunk is written by the agent that wrote the change, so it argues
+its own case. Ask for a **battle review** and a second agent argues the other side.
+
+Say "battle review this branch" (or "challenge these changes") instead of "review this
+branch". The skill runs one pass of Codex over the whole diff, asking it to make the
+strongest case for why each hunk should not be changed at all — or not this way. Each
+piece then shows two voices: the author's what/why, and the adversary's pushback marked
+`nitpick`, `concern`, or `blocking`. Where the adversary has nothing to say, it concedes,
+and the hunk says so in one line — so you always know it looked.
+
+The pushback travels into `export.md` for the pieces you comment on, so the agent
+implementing your comment sees the argument against it too.
+
+Battle review is opt-in and needs the [Codex CLI](https://github.com/openai/codex)
+installed. If Codex is missing or fails, you get the plain review and an explanation —
+it never blocks. Since the adversary has to be independent of the author, the mode is
+unavailable when Codex is the agent running the review.
+
+The gem itself never calls Codex: your agent does the adversarial pass before launching,
+so no model tokens are spent while you read.
+
+## Skills marketplace
+
+The skill lives in its own repo, [hunk-review-changes-skills](https://github.com/lucianghinda/hunk-review-changes-skills), a marketplace that serves every supported agent. `hunk-review-changes install` uses it: it calls the Claude Code plugin CLI, and copies the skill into the directory Codex, Cursor, and OpenCode scan.
+
+## Development
+
+Get the dependencies:
+
+```sh
+bundle install
+```
+
+Run the tests and linter:
+
+```sh
+bundle exec rake
+```
+
+Rebuild the stylesheet after changing `assets/tailwind.css` or the fonts:
+
+```sh
+bundle exec rake css
+```
+
+Release a new version with:
+
+```sh
+bundle exec rake release
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/lucianghinda/hunk-review-changes).
+
+## License
+
+The gem is available as open source under the [MIT License](LICENSE.txt). The bundled Atkinson Hyperlegible fonts are licensed under the [SIL Open Font License](lib/hunk_review_changes/public/fonts/OFL.txt).

data/exe/hunk-review-changes

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/hunk_review_changes"
+
+exit HunkReviewChanges::CLI.start(ARGV)

data/lib/hunk_review_changes/app.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "sinatra/base"
+require "ipaddr"
+require "json"
+require "cgi"
+
+require_relative "markdown"
+require_relative "diff"
+require_relative "state"
+require_relative "export"
+require_relative "lifecycle"
+
+module HunkReviewChanges
+  # The Sinatra app that serves the review UI and collects per-piece comments. It is
+  # configured per run through Sinatra settings so tests can drive it with rack-test
+  # against a fixture bundle and a shutdown stub, instead of a real port and exit!.
+  class App < Sinatra::Base
+    set :views, File.expand_path("views", __dir__)
+    set :public_folder, File.expand_path("public", __dir__)
+    set :bind, "127.0.0.1"
+    set :logging, false
+    enable :static
+
+    # The server only ever binds to loopback, so restrict host authorization to
+    # loopback hosts (guards against DNS-rebinding without depending on the Sinatra
+    # environment, whose default only applies the check in development).
+    set :host_authorization, {
+      permitted_hosts: ["localhost", ".localhost", IPAddr.new("127.0.0.0/8"), IPAddr.new("::1")]
+    }
+
+    # Configured by the server (or a test) before the app handles a request.
+    set :bundle, nil
+    set :state_path, nil
+    set :export_path, nil
+    set :lifecycle, nil
+
+    class << self
+      # The shutdown callback is stored outside Sinatra settings on purpose: a setting
+      # whose value responds to #call is auto-invoked when read, which would fire the
+      # shutdown the moment a route touched it. A plain accessor holds the callable.
+      attr_accessor :on_done
+    end
+
+    helpers do
+      def bundle = settings.bundle
+      def state = State.new(settings.state_path, bundle_id: bundle.fingerprint)
+      # Full HTML-entity escaping (incl. " and ') so values stay safe inside
+      # double-quoted attributes like title="..." and data-nav="...", not only
+      # in text nodes.
+      def esc(str) = CGI.escapeHTML(str.to_s)
+
+      # The adversary's rebuttal, ready for the view, or nil when the piece was never
+      # challenged. Its argument goes through the same Markdown pipeline as what/why,
+      # so it gets the same URL sanitizing — the adversary's prose is bundle input like
+      # any other, not a trusted source.
+      def challenge_view(challenge)
+        return nil unless challenge.is_a?(Hash)
+
+        { stance: challenge["stance"].to_s, argument: Markdown.inline(challenge["argument"]) }
+      end
+    end
+
+    get "/" do
+      review_state = state
+      total = bundle.pieces.size
+      @target = bundle.target
+      @resolved_by = bundle.resolved_by
+      @framing = Markdown.inline(bundle.framing)
+      @adversary = bundle.adversary
+      @pieces = bundle.pieces.map do |piece|
+        entry = review_state[piece["id"]]
+        {
+          id: piece["id"],
+          n: "#{piece["id"]} of #{total}",
+          file: piece["file"],
+          label: piece["label"],
+          kind: piece["kind"] || "code",
+          what: Markdown.inline(piece["what"]),
+          why: Markdown.inline(piece["why"]),
+          flags: Array(piece["flags"]).map { |flag| Markdown.inline(flag) },
+          comment: entry["comment"].to_s,
+          flagged: !!entry["flag"],
+          reviewed: !!entry["reviewed"],
+          status: State.status_for(entry),
+          challenge: challenge_view(piece["challenge"]),
+          diff: Diff.to_html(piece["diff"], piece["file"])
+        }
+      end
+      # Provenance only earns its line when a rebuttal actually survived to the page:
+      # naming the adversary above a page with no challenges would overstate what ran.
+      @adversary = nil unless @pieces.any? { |piece| piece[:challenge] }
+      erb :index
+    end
+
+    post "/pieces/:id" do
+      content_type :json
+      body = parse_body
+      status = state.update(
+        params["id"],
+        comment: body["comment"],
+        flag: body["flag"],
+        reviewed: body["reviewed"]
+      )
+      { ok: true, status: status }.to_json
+    end
+
+    get "/export.md" do
+      content_type "text/plain"
+      Export.new(bundle, state).to_markdown
+    end
+
+    post "/done" do
+      content_type :json
+      File.write(settings.export_path, Export.new(bundle, state).to_markdown)
+      self.class.on_done&.call
+      { ok: true, export: settings.export_path }.to_json
+    end
+
+    post "/heartbeat" do
+      settings.lifecycle&.heartbeat!
+      204
+    end
+
+    post "/bye" do
+      settings.lifecycle&.bye!
+      204
+    end
+
+    private
+
+    def parse_body
+      JSON.parse(request.body.read)
+    rescue StandardError
+      {}
+    end
+  end
+end

data/lib/hunk_review_changes/assets.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "rouge"
+
+module HunkReviewChanges
+  # Generates the syntax-highlighting CSS shipped in app.css. Kept out of the request
+  # path: `rake css` renders it once at build time so the running server only reads a
+  # static file. Two themes are emitted under the same `.highlight` scope; the dark one
+  # is wrapped in a prefers-color-scheme media query so the page follows the OS setting
+  # with no toggle and no JavaScript.
+  module Assets
+    LIGHT_THEME = "github"
+    DARK_THEME = "github.dark"
+
+    module_function
+
+    def rouge_css
+      light = Rouge::Theme.find(LIGHT_THEME).new(scope: ".highlight").render
+      dark = Rouge::Theme.find(DARK_THEME).new(scope: ".highlight").render
+      <<~CSS
+        /* Syntax highlighting — generated by `rake css` from Rouge themes. */
+        #{light}
+        @media (prefers-color-scheme: dark) {
+        #{indent(dark)}
+        }
+      CSS
+    end
+
+    def indent(text, spaces = 2)
+      pad = " " * spaces
+      text.each_line.map { |line| line.strip.empty? ? line : "#{pad}#{line}" }.join
+    end
+  end
+end

data/lib/hunk_review_changes/bundle.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+
+module HunkReviewChanges
+  # Loads and validates a bundle.json written by the companion skill. Validation
+  # exists to catch the exact failure modes the skill warns about (a malformed diff,
+  # missing pieces, non-sequential ids) and report them with a message the agent that
+  # wrote the bundle can act on, instead of a blank or broken page.
+  class Bundle
+    class Error < StandardError
+    end
+
+    # The adversarial stances a piece's challenge may take, weakest to strongest.
+    # Shared so the validator, the viewer's badge map, and the export all agree on
+    # the same four strings instead of each carrying its own copy.
+    STANCES = %w[concede nitpick concern blocking].freeze
+
+    attr_reader :path, :data
+
+    def self.load(path)
+      new(path).tap(&:validate!)
+    end
+
+    def initialize(path)
+      @path = path
+      raise Error, "no such bundle: #{path}" unless File.exist?(path)
+
+      @data = JSON.parse(File.read(path))
+    rescue JSON::ParserError => e
+      raise Error, "bundle is not valid JSON (#{e.message}). " \
+                   "Write it with real JSON — no trailing commas or comments."
+    end
+
+    def target = data["target"]
+    def resolved_by = data["resolved_by"]
+    def framing = data["framing"]
+    def pieces = data["pieces"]
+    def adversary = data["adversary"]
+    def dir = File.dirname(File.expand_path(path))
+
+    # Stable identity for this bundle's content, used to scope persisted review
+    # state so a reused directory never replays another bundle's comments.
+    def fingerprint = Digest::SHA256.hexdigest(JSON.generate(data))
+
+    def validate!
+      raise Error, "bundle must be a JSON object with a \"pieces\" array" unless data.is_a?(Hash)
+
+      list = data["pieces"]
+      raise Error, "bundle has no \"pieces\" array" unless list.is_a?(Array)
+      raise Error, "bundle \"pieces\" array is empty — nothing to review" if list.empty?
+
+      list.each_with_index { |piece, index| validate_piece!(piece, index) }
+      self
+    end
+
+    private
+
+    def validate_piece!(piece, index)
+      position = index + 1
+      raise Error, "piece ##{position} must be a JSON object" unless piece.is_a?(Hash)
+
+      expected_id = index + 1
+      unless piece["id"] == expected_id
+        raise Error, "piece ##{position} has id #{piece["id"].inspect}; ids must be " \
+                     "1-based and sequential (expected #{expected_id})"
+      end
+
+      %w[file label].each do |field|
+        if piece[field].to_s.strip.empty?
+          raise Error, "piece #{expected_id} is missing a non-empty \"#{field}\""
+        end
+      end
+
+      validate_diff!(piece, expected_id)
+      validate_challenge!(piece, expected_id)
+    end
+
+    # A challenge is optional: a bundle written without an adversarial pass has none,
+    # and must stay valid. When one is present it has to be usable by the viewer, so
+    # the stance must be a known one (it selects a badge) and a piece that claims an
+    # objection must actually state it.
+    def validate_challenge!(piece, id)
+      challenge = piece["challenge"]
+      return if challenge.nil?
+
+      unless challenge.is_a?(Hash)
+        raise Error, "piece #{id} \"challenge\" must be a JSON object with \"stance\" and " \
+                     "\"argument\" keys"
+      end
+
+      stance = challenge["stance"]
+      unless STANCES.include?(stance)
+        raise Error, "piece #{id} \"challenge\" has stance #{stance.inspect}; expected one of " \
+                     "#{STANCES.join(", ")}"
+      end
+
+      return if stance == "concede" || !challenge["argument"].to_s.strip.empty?
+
+      raise Error, "piece #{id} \"challenge\" has stance \"#{stance}\" but an empty " \
+                   "\"argument\" — state the objection, or use stance \"concede\""
+    end
+
+    def validate_diff!(piece, id)
+      diff = piece["diff"].to_s
+      if diff.strip.empty?
+        raise Error, "piece #{id} has an empty \"diff\" — copy a real unified-diff hunk from git"
+      end
+
+      unless diff.include?("@@")
+        raise Error, "piece #{id} \"diff\" has no @@ hunk header — copy the whole hunk " \
+                     "including the @@ ... @@ line so line numbers can render"
+      end
+
+      return unless diff.include?('\n') && !diff.include?("\n")
+
+      raise Error, "piece #{id} \"diff\" looks escaped (literal \\n, no real newlines) — " \
+                   "the diff must contain actual newlines, not \\n sequences"
+    end
+  end
+end

data/lib/hunk_review_changes/cli.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+require_relative "version"
+require_relative "bundle"
+
+module HunkReviewChanges
+  # Command-line entry point. Two commands:
+  #
+  #   hunk-review-changes <bundle.json> [--port N] [--no-open]   serve the review UI
+  #   hunk-review-changes install [--agent ...] [--marketplace-repo ...]
+  #
+  # `serve` is the default, so a bare bundle path just works (that is how the skill
+  # launches it).
+  class CLI
+    class Error < StandardError
+    end
+
+    def self.start(argv)
+      new.run(argv)
+    rescue Bundle::Error, Error, OptionParser::ParseError => e
+      warn "hunk-review-changes: #{e.message}"
+      1
+    end
+
+    def run(argv)
+      argv = argv.dup
+      case argv.first
+      when "install" then install(argv.drop(1))
+      when "-v", "--version" then print_version
+      when "-h", "--help", nil then print_help
+      else serve(argv)
+      end
+    end
+
+    private
+
+    def serve(argv)
+      options = { open: open_by_default? }
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: hunk-review-changes <bundle.json> [--port N] [--no-open]"
+        o.on("--port N", Integer, "Port to bind (default: a free port)") { |n| options[:port] = n }
+        o.on("--no-open", "Do not open the browser automatically") { options[:open] = false }
+      end
+      rest = parser.parse(argv)
+      path = rest.first
+      raise Error, "no bundle given\n#{parser}" unless path
+
+      require_relative "server"
+      bundle = Bundle.load(path)
+      Server.new(bundle, port: options[:port], open: options[:open]).run
+      0
+    end
+
+    def install(argv)
+      options = { repo: MARKETPLACE_REPO }
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: hunk-review-changes install [--agent claude,codex,...] " \
+                   "[--marketplace-repo URL_OR_PATH]"
+        o.on("--agent LIST", Array, "Agents to install for (skips the prompt); or 'all'") do |list|
+          options[:only] = list
+        end
+        o.on("--marketplace-repo REPO", "Marketplace repo URL or local path") do |repo|
+          options[:repo] = repo
+        end
+      end
+      parser.parse(argv)
+
+      require_relative "installer/runner"
+      results = Installer::Runner.new(repo: options[:repo], only: options[:only]).run
+      results.all?(&:ok) ? 0 : 1
+    end
+
+    def open_by_default?
+      ENV["HUNK_REVIEW_CHANGES_NO_OPEN"] != "1"
+    end
+
+    def print_version
+      puts "hunk-review-changes #{VERSION}"
+      0
+    end
+
+    def print_help
+      puts <<~HELP
+        hunk-review-changes #{VERSION}
+
+        Review a diff hunk-by-hunk in your browser, then hand the comments back to
+        your AI coding agent.
+
+        Usage:
+          hunk-review-changes <bundle.json> [--port N] [--no-open]
+              Serve the review UI for a bundle written by the companion skill.
+
+          hunk-review-changes install [--agent claude,codex,cursor,opencode]
+                                      [--marketplace-repo URL_OR_PATH]
+              Install the companion skill into your AI agents. With no --agent flag it
+              asks which agents to install for.
+
+          hunk-review-changes --version
+          hunk-review-changes --help
+      HELP
+      0
+    end
+  end
+end