lux-hammer 0.3.21 → 0.3.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84a9d6339d8a34112c31a210823398ea9122959fff9d3522562f840147e8a130
-  data.tar.gz: f7483553452c4e33d18dad6d9d4e2b764cb13a49a4080ea90f4227689f9fc211
+  metadata.gz: df3eb16fdf398c03d043585e48e4f9792d09b4427f0a0733eefa9725f1f97b0d
+  data.tar.gz: d36961cbeb0e10d44fa5119629a436aeed2d16fa384fbc0256dfb9cf1f9893ec
 SHA512:
-  metadata.gz: e5158a762b7cb292535f58e33b0a8ae84c2f9affe473501cce701784d5a690bebf5c187e3c588df66821a5cd3f3177f83d655149e84426ea8e9a12c578e7e5c8
-  data.tar.gz: 5711d908d489770a4ede0507224f0a6cf3dbe761edddaed0f6c4591b0e1a1e070e4727f8000829c861cc215be8baf238933b6591d996bb8ee500742d70d22aa5
+  metadata.gz: 8429a1a3a276bca73309522c57c78f3283a78ed327cb0d4354757c3bccd06bf5a0202af888f5ebfa8e66c01850cb4cf927317b8c68970a18b3a9370ff5a70516
+  data.tar.gz: 68ffb3baf274099eae5e3c3398f77bbda5163c3867980772c737e06d211a8ce26de08702f51e53b8d27c067703eedaac482f5e4f7c2b133e638272ef10b319c6

data/.version

@@ -1 +1 @@
-0.3.21
+0.3.22

data/lib/hammer/shell.rb

@@ -88,26 +88,43 @@ class Hammer
     #
     #   idx = choose 'Pick env', %w[dev staging prod]
     #   say.green "chose #{ %w[dev staging prod][idx] }" if idx
-    def choose(prompt, items)
+    #
+    # `skip` marks rows that are shown but never landed on, so a list can
+    # carry its own headings and rules. They are drawn in gray, the cursor
+    # steps over them, and the returned index still counts every row:
+    #
+    #   choose 'Pick', ['-- fast --', 'dev', '-- slow --', 'prod'],
+    #          skip: ->(item) { item.start_with?('--') }
+    def choose(prompt, items, skip: nil)
       items = items.to_a
       error 'choose needs at least one item' if items.empty?
 
+      live = items.each_index.reject { |i| skip&.call(items[i]) }
+      error 'choose needs at least one selectable item' if live.empty?
+
       say.cyan prompt
 
-      return choose_numbered(items) unless $stdin.tty? && $stdin.respond_to?(:raw)
+      return choose_numbered(items, live) unless $stdin.tty? && $stdin.respond_to?(:raw)
 
-      selected = 0
+      selected = live.first
       # In raw mode \n is not translated to \r\n, so the picker uses \r\n
       # explicitly. The initial draw happens in cooked mode but \r\n is
       # harmless there.
       redraw = lambda do |highlight = :cyan|
         items.each_with_index do |item, i|
-          line = i == selected ? paint("> #{item}", highlight) : "  #{item}"
+          line = if !live.include?(i) then paint("  #{item}", :gray)
+                 elsif i == selected  then paint("> #{item}", highlight)
+                 else                      "  #{item}"
+                 end
           $stdout.print "#{line}\r\n"
         end
       end
       redraw.call
 
+      # Move by position among the selectable rows, so skipped ones are
+      # stepped over in both directions and the wrap-around still works.
+      step = ->(dir) { live[(live.index(selected) + dir) % live.size] }
+
       $stdout.print "\e[?25l" # hide cursor
       begin
         $stdin.raw do |io|
@@ -126,15 +143,15 @@ class Hammer
               # ESC may stand alone or start an arrow sequence \e[A / \e[B.
               if IO.select([io], nil, nil, 0.01) && io.getch == '['
                 case io.getch
-                when 'A' then selected = (selected - 1) % items.size
-                when 'B' then selected = (selected + 1) % items.size
+                when 'A' then selected = step.call(-1)
+                when 'B' then selected = step.call(1)
                 end
               else
                 $stdout.print "\e[#{items.size}A\r\e[J"
                 return nil
               end
-            when 'k' then selected = (selected - 1) % items.size
-            when 'j' then selected = (selected + 1) % items.size
+            when 'k' then selected = step.call(-1)
+            when 'j' then selected = step.call(1)
             end
             $stdout.print "\e[#{items.size}A\r\e[J"
             redraw.call
@@ -146,13 +163,17 @@ class Hammer
     end
 
     # Fallback for non-TTY stdin (pipes, tests). Returns the index or nil.
-    def choose_numbered(items)
-      items.each_with_index { |item, i| puts "  #{i + 1}) #{item}" }
-      print paint("select [1-#{items.size}]: ", :cyan)
+    # Skipped rows are still printed, just without a number to type.
+    def choose_numbered(items, live = items.each_index.to_a)
+      items.each_with_index do |item, i|
+        n = live.index(i)
+        puts n ? "  #{n + 1}) #{item}" : "     #{item}"
+      end
+      print paint("select [1-#{live.size}]: ", :cyan)
       line = $stdin.gets
       return nil if line.nil?
       idx = line.strip.to_i - 1
-      idx.between?(0, items.size - 1) ? idx : nil
+      idx.between?(0, live.size - 1) ? live[idx] : nil
     end
 
     # Run a shell command. Echoes the command in gray, raises

data/recipes/lib/llm/plan.rb

@@ -0,0 +1,651 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+require 'json'
+
+# Applies a /plan bundle - a JSON file that pairs every intended edit with the
+# sha1 its target had when the plan was written.
+#
+# The point is a fast apply after slow planning: a file whose sha1 still
+# matches is written without anyone re-reading it, and a file that drifted is
+# handed back to the caller with the intent and the wanted text, to be applied
+# by judgement instead of by string match. Nothing here calls an LLM; it tells
+# the one that is already running what is left to do.
+#
+# Safety rules that hold regardless of the bundle:
+#   - a file is only written once every hunk in it resolves, so no file is
+#     ever left half-edited
+#   - writes go through a temp file and a rename, keeping the original mode
+#   - every touched file is copied under <slug>.bak before it changes, and the
+#     undo log is flushed per file so a crash mid-run is still revertible
+#   - paths must stay inside the working tree and may not be symlinks
+#   - a bundle that already landed re-runs as a no-op, not as drift
+module LlmPlan
+  Error = Class.new(StandardError)
+
+  class << self
+    # plan.md is the only copy of the prose: `llm plan` prints it whole, and
+    # the per-command help is composed from its sections.
+    def readme
+      @readme ||= File.read(File.join(__dir__, 'plan.md'))
+    end
+
+    # The body of one `## Section`, without its heading. Trims blank lines
+    # only - stripping whitespace would eat the first line's indentation and
+    # break the code blocks this composes into command help.
+    def section(title)
+      body = readme[/^## #{Regexp.escape(title)}\s*\n(.*?)(?=^## |\z)/m, 1]
+      raise Error, "plan.md has no '#{title}' section" unless body
+      body.sub(/\A\n+/, '').rstrip
+    end
+  end
+
+  # One planned file operation, plus everything needed to decide whether the
+  # world still looks the way the plan assumed.
+  class Entry
+    OPS          = %w[create change delete].freeze
+    PAST         = { 'create' => 'created', 'change' => 'changed', 'delete' => 'deleted' }.freeze
+    ANCHOR_WIDTH = 60
+
+    attr_reader :path, :op, :sha1
+
+    def initialize(raw, root:)
+      @raw  = raw
+      @root = root
+      @path = raw['path'].to_s
+      @op   = raw['op'].to_s
+      @sha1 = raw['sha1'].to_s
+      validate!
+    end
+
+    def hunks   = Array(@raw['hunks'])
+    def content = @raw['content'].to_s
+    def past    = PAST[op]
+
+    # The one-clause summary for the manifest. Falls back to the hunk intents,
+    # so a change usually needs no `note` of its own.
+    def note
+      given = @raw['note'].to_s.strip
+      return given unless given.empty?
+
+      hunks.filter_map { |hunk| hunk['intent'].to_s.strip if hunk['intent'] }.reject(&:empty?).join('; ')
+    end
+
+    # sha1 of the file as it is right now, or nil when it is not there.
+    def current_sha1
+      File.file?(abs) ? Digest::SHA1.file(abs).hexdigest : nil
+    end
+
+    # nil when the file is byte for byte what the plan assumed, otherwise a
+    # sentence the caller can act on.
+    def drift_reason
+      return "#{path} is a symlink, refusing to write through it" if File.symlink?(abs)
+
+      if op == 'create'
+        return nil unless File.exist?(abs)
+        'planned as a new file, but it exists now'
+      else
+        return 'planned file is gone' unless File.file?(abs)
+        got = current_sha1
+        return nil if got == sha1
+        "changed since planning (sha1 #{got[0, 10]}, planned #{sha1[0, 10]})"
+      end
+    end
+
+    # A second run of a bundle that already landed is a no-op, not drift.
+    # `record` is this entry's line from the undo log, or nil.
+    def already_applied?(record)
+      return false unless record
+      return !File.exist?(abs) if op == 'delete'
+      current_sha1 == record['after']
+    end
+
+    # Writes the entry. Returns nil on success, or a reason string naming what
+    # the caller has to finish by hand.
+    def apply!(backup)
+      case op
+      when 'create'
+        FileUtils.mkdir_p File.dirname(abs)
+        write content
+      when 'delete'
+        backup.save abs, path
+        FileUtils.rm_f abs
+      when 'change'
+        body = File.read(abs)
+
+        # Resolve every hunk against the in-memory copy first - a bundle with
+        # one bad anchor leaves the file exactly as it was.
+        hunks.each do |hunk|
+          body, reason = splice(body, hunk)
+          return reason if reason
+        end
+
+        backup.save abs, path
+        write body
+      end
+
+      nil
+    end
+
+    # The file as the hunks would leave it: [body, nil], or [nil, reason] when
+    # an anchor will not resolve. Only meaningful for a change.
+    def preview
+      @preview ||= resolve_preview
+    end
+
+    # Resolves the hunks and throws the result away, so a bad anchor - which is
+    # a planning bug, not drift - surfaces while the plan can still be fixed.
+    def dry_apply
+      return nil unless op == 'change'
+
+      preview.last
+    end
+
+    # [added, removed] line counts. Multiset-wise: a line that only moved
+    # counts as neither, which reads better in a summary than a positional
+    # diff would. Zero for anything that cannot be resolved.
+    def delta
+      case op
+      when 'create' then [content.lines.size, 0]
+      when 'delete' then [0, File.file?(abs) ? File.read(abs).lines.size : 0]
+      else
+        body, = preview
+        body ? line_delta(File.read(abs), body) : [0, 0]
+      end
+    end
+
+    private
+
+    def abs = File.expand_path(path, @root)
+
+    def resolve_preview
+      body = File.read(abs)
+
+      hunks.each do |hunk|
+        body, reason = splice(body, hunk)
+        return [nil, reason] if reason
+      end
+
+      [body, nil]
+    end
+
+    def line_delta(old_body, new_body)
+      before = old_body.lines.tally
+      after  = new_body.lines.tally
+
+      [after.sum  { |line, n| [n - before.fetch(line, 0), 0].max },
+       before.sum { |line, n| [n - after.fetch(line, 0), 0].max }]
+    end
+
+    def validate!
+      raise Error, 'file entry without a path'                if path.empty?
+      raise Error, "#{path}: unknown op #{op.inspect}"         unless OPS.include?(op)
+      raise Error, "#{path}: absolute paths are not allowed"   if path.start_with?('/')
+      raise Error, "#{path}: path escapes the working tree"    unless inside_root?
+      raise Error, "#{path}: create needs content"             if op == 'create' && !@raw.key?('content')
+      raise Error, "#{path}: #{op} needs a sha1"               if op != 'create' && sha1.empty?
+      raise Error, "#{path}: change needs at least one hunk"   if op == 'change' && hunks.empty?
+
+      hunks.each do |hunk|
+        raise Error, "#{path}: hunk needs both old and new"    unless hunk['old'] && hunk['new']
+        raise Error, "#{path}: hunk old and new are identical" if hunk['old'] == hunk['new']
+        raise Error, "#{path}: hunk old is empty"              if hunk['old'].to_s.empty?
+      end
+    end
+
+    def inside_root?
+      File.expand_path(path, @root).start_with?("#{@root}/")
+    end
+
+    # Block form of sub/gsub on purpose: a replacement passed as a string would
+    # read \1 and \& in the new text as backreferences.
+    def splice(body, hunk)
+      old, new = hunk['old'].to_s, hunk['new'].to_s
+      found    = body.scan(old).size
+
+      if hunk['all']
+        return [body, "anchor never matched: #{anchor(old)}"] if found.zero?
+        [body.gsub(old) { new }, nil]
+      else
+        return [body, "anchor matched #{found} times, needs exactly 1: #{anchor(old)}"] unless found == 1
+        [body.sub(old) { new }, nil]
+      end
+    end
+
+    def anchor(text)
+      line = text.lines.first.to_s.strip
+      line.length > ANCHOR_WIDTH ? "#{line[0, ANCHOR_WIDTH - 3]}..." : line
+    end
+
+    def write(body)
+      body += "\n" unless body.empty? || body.end_with?("\n")
+
+      mode = File.exist?(abs) ? File.stat(abs).mode : nil
+      tmp  = "#{abs}.llm-plan.#{Process.pid}"
+
+      File.write tmp, body
+      File.chmod mode, tmp if mode
+      File.rename tmp, abs
+    ensure
+      FileUtils.rm_f tmp if tmp && File.exist?(tmp)
+    end
+  end
+
+  # Copies of everything a run touched, plus the log that says how to undo it.
+  class Backup
+    LOG = '_applied.json'
+
+    def initialize(dir, root:)
+      @dir  = dir
+      @root = root
+      @log  = read_log
+    end
+
+    def record_for(entry)
+      @log.find { |row| row['path'] == entry.path }
+    end
+
+    def save(abs, path)
+      return unless File.exist?(abs)
+
+      dest = File.join(@dir, path.sub(%r{\A\./}, ''))
+      FileUtils.mkdir_p File.dirname(dest)
+      FileUtils.cp abs, dest
+    end
+
+    # Flushed per entry, so an interrupted run is still fully revertible.
+    def note(entry)
+      @log.reject! { |row| row['path'] == entry.path }
+      @log.push 'path' => entry.path, 'op' => entry.op, 'after' => entry.current_sha1
+
+      FileUtils.mkdir_p @dir
+      File.write File.join(@dir, LOG), "#{JSON.pretty_generate(@log)}\n"
+    end
+
+    # Undoes a run: created files go away, changed and deleted files come back
+    # from the copies. Returns the paths it touched.
+    def restore!
+      raise Error, "no backup at #{@dir}" if @log.empty?
+
+      @log.map do |row|
+        path = row['path']
+        abs  = File.expand_path(path, @root)
+
+        if row['op'] == 'create'
+          FileUtils.rm_f abs
+        else
+          src = File.join(@dir, path.sub(%r{\A\./}, ''))
+          raise Error, "backup copy missing for #{path}" unless File.exist?(src)
+          FileUtils.mkdir_p File.dirname(abs)
+          FileUtils.cp src, abs
+        end
+
+        path
+      end
+    end
+
+    private
+
+    def read_log
+      file = File.join(@dir, LOG)
+      File.exist?(file) ? JSON.parse(File.read(file)) : []
+    rescue JSON::ParserError
+      []
+    end
+  end
+
+  # The bundle file: what to do, how to prove it, and what to call the commit.
+  class Bundle
+    attr_reader :path, :slug, :goal, :entries, :verify_commands
+
+    def initialize(path, root: Dir.pwd)
+      @path = File.expand_path(path)
+      @root = File.expand_path(root)
+      raise Error, "no bundle at #{path}" unless File.file?(@path)
+
+      raw              = parse
+      @slug            = raw['slug'].to_s.empty? ? File.basename(@path, '.json') : raw['slug']
+      @goal            = raw['goal'].to_s
+      @commit          = raw['commit'] || {}
+      @verify_commands = Array(raw['verify'])
+      @entries         = Array(raw['files']).map { |file| Entry.new(file, root: @root) }
+
+      raise Error, 'bundle lists no files' if @entries.empty?
+      raise Error, "duplicate path in bundle: #{duplicate}" if duplicate
+    end
+
+    def backup_dir   = File.join(dir, "#{slug}.bak")
+    def message_path = File.join(dir, "#{slug}.msg")
+
+    # Subject and body separated by the blank line git expects.
+    def commit_message
+      [@commit['subject'], @commit['body']].map { |part| part.to_s.strip }.reject(&:empty?).join("\n\n")
+    end
+
+    def write_commit_message!
+      return if commit_message.empty?
+      File.write message_path, "#{commit_message}\n"
+    end
+
+    private
+
+    def dir = File.dirname(@path)
+
+    def parse
+      JSON.parse File.read(@path)
+    rescue JSON::ParserError => e
+      raise Error, "bundle is not valid json: #{e.message}"
+    end
+
+    def duplicate
+      seen = {}
+      @entries.each do |entry|
+        return entry.path if seen[entry.path]
+        seen[entry.path] = true
+      end
+      nil
+    end
+  end
+
+  Applied = Struct.new(:entry, :note)
+  Drifted = Struct.new(:entry, :reason)
+  Verify  = Struct.new(:ok, :failed_command)
+
+  # What one run did. `exit_code` is the whole contract with the shell.
+  class Outcome
+    attr_reader :bundle, :applied, :drifted, :skipped
+    attr_accessor :verify
+
+    def initialize(bundle:, applied:, drifted:, skipped:, check_only:)
+      @bundle     = bundle
+      @applied    = applied
+      @drifted    = drifted
+      @skipped    = skipped
+      @check_only = check_only
+    end
+
+    def check_only? = @check_only
+    def clean?      = @drifted.empty?
+    def touched?    = @applied.any?
+
+    def exit_code
+      return 10 unless clean?
+      return 20 if verify && !verify.ok
+      0
+    end
+  end
+
+  # Drives a bundle. Prints nothing - the caller owns the terminal.
+  class Runner
+    def initialize(bundle, root: Dir.pwd)
+      @bundle = bundle
+      @root   = File.expand_path(root)
+      @backup = Backup.new(bundle.backup_dir, root: @root)
+    end
+
+    def apply(check_only: false)
+      applied, drifted, skipped = [], [], []
+
+      @bundle.entries.each do |entry|
+        next skipped.push(entry) if entry.already_applied?(@backup.record_for(entry))
+
+        reason = entry.drift_reason
+        next drifted.push(Drifted.new(entry, reason)) if reason
+
+        if check_only
+          problem = entry.dry_apply
+          next drifted.push(Drifted.new(entry, problem)) if problem
+          next applied.push(Applied.new(entry, 'would apply'))
+        end
+
+        failure = entry.apply!(@backup)
+
+        if failure
+          drifted.push Drifted.new(entry, failure)
+        else
+          @backup.note entry
+          applied.push Applied.new(entry, entry.past)
+        end
+      end
+
+      @bundle.write_commit_message! if applied.any? && !check_only
+
+      Outcome.new(bundle: @bundle, applied:, drifted:, skipped:, check_only:)
+    end
+
+    # Runs the verify commands in order, stopping at the first failure. Their
+    # output streams straight through - the caller wants to read it. Yields
+    # each command first so the caller can announce it.
+    def verify
+      @bundle.verify_commands.each do |cmd|
+        yield cmd if block_given?
+        return Verify.new(false, cmd) unless system(cmd)
+      end
+
+      Verify.new(true, nil)
+    end
+
+    def revert = @backup.restore!
+  end
+
+  # The grouped, sorted view of what a bundle would do: the answer to "what am
+  # I approving?". Holds no formatting - both renderers read it.
+  class Manifest
+    GROUPS = { 'create' => 'Created', 'change' => 'Changed', 'delete' => 'Deleted' }.freeze
+
+    Group = Struct.new(:op, :title, :files, :problems)
+    Row   = Struct.new(:path, :note, :added, :removed)
+
+    def initialize(outcome)
+      @outcome = outcome
+    end
+
+    def goal             = @outcome.bundle.goal
+    def verify_commands  = @outcome.bundle.verify_commands
+    def clean?           = @outcome.drifted.empty?
+
+    def groups
+      @groups ||= GROUPS.filter_map do |op, title|
+        files    = rows_for(op)
+        problems = @outcome.drifted.select { |drifted| drifted.entry.op == op }.sort_by { |d| d.entry.path }
+        next if files.empty? && problems.empty?
+
+        Group.new(op, title, files, problems)
+      end
+    end
+
+    # Columns at which the clause and the counts start, so rows line up.
+    # Problem rows share the path column, or they run into their own message.
+    def width
+      @width ||= (groups.flat_map { |group| group.files.map(&:path) + group.problems.map { |d| d.entry.path } }
+                        .map(&:length).max || 0) + 4
+    end
+
+    def note_width
+      @note_width ||= (groups.flat_map(&:files).map { |file| file.note.length }.max || 0) + 4
+    end
+
+    # "+23 -45" over every file in the plan.
+    def totals
+      files = groups.flat_map(&:files)
+      [files.sum(&:added), files.sum(&:removed)]
+    end
+
+    def tally
+      ready    = @outcome.applied.size + @outcome.skipped.size
+      problems = @outcome.drifted.size
+      added, removed = totals
+      counted  = "#{count(ready, 'file')}, +#{added} -#{removed}"
+      return "#{counted}, anchors resolve" if problems.zero?
+
+      "#{counted}, #{count(problems, 'problem')} - fix the plan before \"go\""
+    end
+
+    private
+
+    def rows_for(op)
+      ready = @outcome.applied.map(&:entry).select { |entry| entry.op == op }
+                      .map { |entry| row_for(entry, entry.note) }
+      done  = @outcome.skipped.select { |entry| entry.op == op }
+                      .map { |entry| row_for(entry, [entry.note, '(already applied)'].reject(&:empty?).join(' ')) }
+
+      (ready + done).sort_by(&:path)
+    end
+
+    def row_for(entry, note)
+      added, removed = entry.delta
+      Row.new(entry.path, note, added, removed)
+    end
+
+    def count(number, noun)
+      "#{number} #{noun}#{'s' unless number == 1}"
+    end
+  end
+
+  # The manifest as markdown, for pasting into a reply. The file list goes in a
+  # ```diff fence: a renderer colours those rows by their leading sign, which
+  # is the only way to get green and red into pasted markdown.
+  class MarkdownReport
+    SIGNS = { 'create' => '+', 'change' => '!', 'delete' => '-' }.freeze
+
+    def initialize(outcome)
+      @manifest = Manifest.new(outcome)
+    end
+
+    def to_s = lines.join("\n")
+
+    def lines
+      rows = []
+      rows << "**#{@manifest.goal}**" << '' unless @manifest.goal.empty?
+
+      rows << '```diff'
+      @manifest.groups.each do |group|
+        sign = SIGNS[group.op]
+        group.files.each { |file| rows << "#{sign} #{columns(file)}" }
+        group.problems.each { |drifted| rows << "! #{drifted.entry.path.ljust(@manifest.width)}PROBLEM #{drifted.reason}" }
+      end
+      rows << '```' << ''
+
+      rows << "verify: #{@manifest.verify_commands.map { |cmd| "`#{cmd}`" }.join(', ')}" if @manifest.verify_commands.any?
+      rows << @manifest.tally
+      rows
+    end
+
+    private
+
+    def columns(file)
+      "#{file.path.ljust(@manifest.width)}#{file.note.ljust(@manifest.note_width)}+#{file.added} -#{file.removed}"
+    end
+  end
+
+  # Turns an Outcome into lines of [text, color] for the CLI to print. Kept
+  # apart from Runner so the wording is testable without a terminal.
+  class Report
+    # Colour per operation, so a group reads at a glance.
+    OP_COLORS = { 'create' => :green, 'change' => :yellow, 'delete' => :red }.freeze
+    PLAIN     = ->(text, _color) { text }
+
+    # `paint` is injected rather than imported: the terminal owns colour, this
+    # class only says which words deserve it, and tests read plain strings.
+    def initialize(outcome, paint: PLAIN)
+      @outcome  = outcome
+      @manifest = Manifest.new(outcome)
+      @paint    = paint
+    end
+
+    def lines
+      @outcome.check_only? ? manifest : result
+    end
+
+    private
+
+    # What a run did, in the past tense.
+    def result
+      rows = []
+      @outcome.applied.each { |applied| rows << ["  ok    #{applied.entry.path} (#{applied.note})", :green] }
+      @outcome.skipped.each { |entry|   rows << ["  ok    #{entry.path} (already applied)", :gray] }
+      rows << ['', nil] if rows.any? && @outcome.drifted.any?
+
+      @outcome.drifted.each { |drifted| rows.concat drift_block(drifted) }
+      rows.concat summary
+      rows
+    end
+
+    # What a run would do, for a human to approve. One line per file, grouped
+    # and sorted, each with its own clause. Never counts of lines touched -
+    # that says nothing about whether the change is the right one.
+    def manifest
+      rows = []
+
+      @manifest.groups.each do |group|
+        rows << [paint(group.title, OP_COLORS[group.op]), nil]
+        rows.concat group.files.map { |file| [file_row(file), nil] }
+
+        group.problems.each_with_index do |drifted, index|
+          rows << ['', nil] unless index.zero? && group.files.empty?
+          rows << ["  #{paint("PROBLEM #{drifted.entry.path}", :red)}", nil]
+          rows << ["  #{paint(drifted.reason, :yellow)}", nil]
+        end
+
+        rows << ['', nil]
+      end
+
+      commands = @manifest.verify_commands
+      rows << ["#{paint('verify:', :magenta)} #{commands.join(', ')}", :gray] if commands.any?
+      rows << [@manifest.tally, @manifest.clean? ? :green : :red]
+      rows
+    end
+
+    # "  ./path        clause        +3 -1", padded before painting so the
+    # invisible escape codes never throw the columns off.
+    def file_row(file)
+      ['  ',
+       paint(file.path.ljust(@manifest.width), :cyan),
+       file.note.ljust(@manifest.note_width),
+       paint("+#{file.added}", :green),
+       ' ',
+       paint("-#{file.removed}", :red)].join
+    end
+
+    def paint(text, color) = @paint.call(text, color)
+
+    def drift_block(drifted)
+      entry = drifted.entry
+      rows  = [["  DRIFT #{entry.path}", :red],
+               ["  #{drifted.reason}. apply this yourself against the current file:", :yellow]]
+
+      case entry.op
+      when 'delete'
+        rows << ['  intent: delete this file - confirm that is still right', nil]
+      when 'create'
+        rows << ['  intent: this content was planned as new - merge it in', nil]
+        rows << ['  --- wanted content ---', :gray]
+        rows << [entry.content, nil]
+        rows << ['  ----------------------', :gray]
+      when 'change'
+        entry.hunks.each do |hunk|
+          rows << ["  intent: #{hunk['intent']}", nil] if hunk['intent']
+          rows << ['  --- wanted old ---', :gray]
+          rows << [hunk['old'], nil]
+          rows << ['  --- wanted new ---', :gray]
+          rows << [hunk['new'], nil]
+          rows << ['  ------------------', :gray]
+        end
+      end
+
+      rows << ['', nil]
+      rows
+    end
+
+    def summary
+      done = @outcome.applied.size + @outcome.skipped.size
+      rows = [["  #{done} applied, #{@outcome.drifted.size} needs you", nil]]
+      return rows unless @outcome.touched?
+
+      rows << ["  backup: #{@outcome.bundle.backup_dir}/", :gray]
+      rows << ["  revert: llm plan:revert #{@outcome.bundle.path}", :gray]
+      rows
+    end
+  end
+end

data/recipes/lib/llm/wrap.rb

@@ -3,6 +3,7 @@
 require 'fileutils'
 require 'io/console'
 require 'pty'
+require 'shellwords'
 
 # Run a command in a PTY with the last prompts you typed pinned to the bottom
 # rows of the screen, under a "prompt history" rule.
@@ -151,6 +152,66 @@ module LlmWrap
     end
   end
 
+  # The commands `llm wrap` offers when asked for no particular one. Plain
+  # text, one command per line - nothing to learn, editable with anything.
+  #
+  # A # comment is dropped, so a command can be parked without being deleted.
+  # A line with no letter in it is kept but not runnable: blanks and ---- rules
+  # stay visible in the picker to group the list, the cursor just steps over
+  # them. No executable name is spelled without a letter, so nothing real is
+  # caught by that.
+  module Config
+    DEFAULTS ||= [
+      'claude --dangerously-skip-permissions --continue',
+      'codex resume --last --dangerously-bypass-approvals-and-sandbox',
+      'grok --always-approve --continue'
+    ].freeze
+
+    # A method rather than a constant for the same reason as Handoff.dir: the
+    # tests need somewhere else to write.
+    def self.path
+      ENV['LLM_WRAP_CONFIG'] || File.expand_path('~/.config/hammer/llm-wrap.txt')
+    end
+
+    def self.lines
+      return [] unless File.file?(path)
+
+      # Decide what to keep first, then tidy what survived - lstrip inside the
+      # test so an indented # is still a comment.
+      File.readlines(path, chomp: true)
+          .reject { |line| line.lstrip.start_with?('#') }
+          .map(&:strip)
+    rescue SystemCallError, IOError
+      []
+    end
+
+    # A row the picker shows but will not run. Nothing without a letter in it
+    # can name a program, which makes ---- and a blank line free to use as
+    # dividers without needing a syntax for them.
+    def self.runnable?(line)
+      line.match?(/[a-z]/i)
+    end
+
+    # Split rather than hand the line over whole: PTY.spawn passes a
+    # one-element argv to /bin/sh, and a command out of this file should reach
+    # the wrapper the same way `llm wrap claude --foo` already does - as argv,
+    # no shell in between.
+    def self.argv(line)
+      Shellwords.split(line)
+    end
+
+    # Writes DEFAULTS when there is nothing there yet - no file, or one that is
+    # only whitespace. A file holding just commented-out lines is left alone;
+    # those are someone's notes, not an empty file.
+    def self.seed
+      return false if File.file?(path) && !File.read(path).strip.empty?
+
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, "#{DEFAULTS.join("\n")}\n")
+      true
+    end
+  end
+
   class Session
     def initialize(argv, keep, origin = argv)
       @argv     = argv

data/recipes/llm.rb

@@ -7,6 +7,7 @@ desc <<~TXT
 
   Namespaces:
     memory   persistent memory store (backs the Claude Code memory plugin)
+    plan     apply a /plan bundle - sha1 checked, drift aware
     prompt   token-prefix prompt expander (UserPromptSubmit hook + CLI)
 
   Commands:
@@ -23,6 +24,7 @@ require 'set'
 # checkout still load matching lib/, not an older installed gem copy).
 _llm_root = File.dirname(File.realpath(__FILE__))
 require File.join(_llm_root, 'lib/llm/usage')
+require File.join(_llm_root, 'lib/llm/plan')
 
 STORE        ||= ENV['CLAUDE_MEMORY_STORE'] || File.expand_path('~/dev/ai/memory')
 VALID_TYPES  ||= %w[user feedback project reference].freeze
@@ -40,10 +42,10 @@ task :usage do
     `~/.cache/llm/claude-limits.json`, falling back to the OAuth usage API. `month` shows
     Claude extra-usage credits (API only, and only when you've enabled them).
   D
-  example 'llm usage'
-  example 'llm usage month'
-  example 'llm usage --json'
-  example 'llm usage --provider grok'
+  example 'usage'
+  example 'usage month'
+  example 'usage --json'
+  example 'usage --provider grok'
 
   # :period is declared first on purpose — the parser fills un-set scalar opts
   # from positionals in declaration order, so `llm usage month` must reach
@@ -108,27 +110,59 @@ task :wrap do
 
     Put `--` before the wrapped command when it has flags of its own, otherwise they are
     parsed as flags to `llm wrap`.
+
+    With no command at all, the commands in ~/.config/hammer/llm-wrap.txt are offered in
+    an arrow-key picker instead. That file is plain text, one command per line. A line
+    starting with # is dropped, and a line with no letter in it stays on screen but
+    cannot be picked - so blanks and ---- rules group the list without being in the way.
+    `--config` opens it in $EDITOR, writing a starting set the first time.
   D
-  example 'llm wrap claude'
-  example 'llm wrap -- claude --resume'
-  example 'llm wrap --lines 5 -- bash -l'
+  example 'wrap'
+  example 'wrap --config'
+  example 'wrap claude'
+  example 'wrap -- claude --resume'
+  example 'wrap --lines 5 -- bash -l'
 
   # `positional: false` is load-bearing: the parser fills un-set scalar opts
   # from positionals in declaration order, so without it `llm wrap claude`
-  # would hand "claude" to --lines and die on the integer cast.
+  # would hand "claude" to --lines and die on the integer cast. `--config` is
+  # boolean, which the parser skips over, so it needs no such guard.
   opt :lines, type: :integer, default: 3, positional: false,
               desc: 'how many recent prompts to pin', placeholder: 'N'
+  opt :config, type: :boolean, desc: 'open the command list in $EDITOR'
 
   proc do |opts|
-    cmd = Array(opts[:args])
-    error 'usage: llm wrap [--lines N] [--] <command> [args...]' if cmd.empty?
-
     # Required lazily - llm.rb also runs as a per-prompt hook (`llm prompt
     # hook`), which should not pay to load pty/io-console. `_llm_root` is a
     # local from the file scope; the block closes over it (instance_exec
     # rebinds self, not locals).
     require File.join(_llm_root, 'lib/llm/wrap')
 
+    if opts[:config]
+      editor = ENV['EDITOR'] || ENV['VISUAL']
+      error '$EDITOR not set' unless editor
+      say.green "created #{LlmWrap::Config.path}" if LlmWrap::Config.seed
+      exit system(editor, LlmWrap::Config.path) ? 0 : 1
+    end
+
+    cmd = Array(opts[:args])
+
+    # Nothing asked for: offer the list rather than a usage error. The picker
+    # shows each line as it was written - re-joining a split argv would quote
+    # it back differently from what is in the file.
+    if cmd.empty?
+      LlmWrap::Config.seed
+      choices = LlmWrap::Config.lines
+      unless choices.any? { |line| LlmWrap::Config.runnable?(line) }
+        error "no commands in #{LlmWrap::Config.path} - add one with: llm wrap --config"
+      end
+
+      idx = choose('wrap which command?', choices, skip: ->(line) { !LlmWrap::Config.runnable?(line) })
+      next say.gray('cancelled') unless idx
+
+      cmd = LlmWrap::Config.argv(choices[idx])
+    end
+
     # The wrapper renames itself after the program it runs, so that a pane
     # watcher can still see which agent is in there - which leaves nothing
     # behind that says how the pane was started. This is that: the invocation
@@ -179,7 +213,7 @@ namespace :memory do
 
   task :list do
     desc 'List stored memories with type and one-line description'
-    example 'llm memory list'
+    example 'memory list'
 
     proc do
       files = Dir[File.join(STORE, '*.md')].sort
@@ -199,7 +233,7 @@ namespace :memory do
 
   task :read do
     desc 'Print the full content of a memory (frontmatter + body)'
-    example 'llm memory read user-role'
+    example 'memory read user-role'
 
     proc do |opts|
       name = opts[:args].first
@@ -251,7 +285,7 @@ namespace :memory do
 
   task :delete do
     desc 'Delete a memory by name'
-    example 'llm memory delete old-fact'
+    example 'memory delete old-fact'
 
     proc do |opts|
       name = opts[:args].first
@@ -265,7 +299,7 @@ namespace :memory do
 
   task :search do
     desc 'Search memory bodies for a query string (case-insensitive)'
-    example 'llm memory search react'
+    example 'memory search react'
 
     proc do |opts|
       query = opts[:args].first
@@ -524,8 +558,8 @@ namespace :prompt do
 
   task :expand do
     desc 'Expand prompt token(s) and print the resulting context'
-    example 'llm prompt:expand :foo :bar'
-    example 'llm prompt:expand foo:'
+    example 'prompt:expand :foo :bar'
+    example 'prompt:expand foo:'
 
     proc do |opts|
       input = opts[:args].join(' ')
@@ -561,3 +595,104 @@ namespace :prompt do
     end
   end
 end
+
+# The namespace's sibling task: `llm plan` explains the thing, `llm plan:*`
+# does it. The command list underneath is hammer's own, not a copy.
+task :plan do
+  desc 'How the /plan bundle apply works: logic, bundle format, exit codes'
+  example 'plan'
+
+  proc do
+    say LlmPlan.readme
+    say ''
+    self.class.print_help 'plan:'
+  end
+end
+
+namespace :plan do
+  # Helpers live inside the namespace block for the same reason as :memory -
+  # a top-level `helpers do` lands on the root class, which namespaces do not
+  # inherit from.
+  private
+
+  def load_bundle(opts)
+    path = opts[:args].first
+    error 'usage: llm plan:<apply|check|verify|revert> ./tmp/plan-[SLUG].json' unless path
+    LlmPlan::Bundle.new(path)
+  rescue LlmPlan::Error => e
+    error e.message
+  end
+
+  # Hammer owns colour (and turns it off for a non-tty), so hand its painter
+  # to the report rather than teaching the report about ANSI.
+  def render(outcome)
+    report = LlmPlan::Report.new(outcome, paint: Hammer::Shell.method(:paint))
+    report.lines.each { |text, color| say text, color }
+  end
+
+  def run_verify(runner)
+    result = runner.verify { |cmd| say "  > #{cmd}", :cyan }
+    result.ok ? say('  verify ok', :green) : say("  FAIL #{result.failed_command}", :red)
+    result
+  end
+
+  task :apply do
+    # Composed from plan.md rather than written out again - see `llm plan`.
+    desc ['Apply a /plan bundle: sha1-checked edits now, drift handed back to you.',
+          "The bundle, normally ./tmp/plan-[SLUG].json:\n\n#{LlmPlan.section('The bundle')}",
+          LlmPlan.section('Drift'),
+          LlmPlan.section('Exit codes')].join("\n\n")
+    example 'plan:apply ./tmp/plan-note-anchor.json'
+
+    proc do |opts|
+      bundle  = load_bundle(opts)
+      runner  = LlmPlan::Runner.new(bundle)
+      outcome = runner.apply
+
+      render outcome
+      outcome.verify = run_verify(runner) if outcome.clean?
+
+      exit outcome.exit_code
+    end
+  end
+
+  task :check do
+    desc ['Dry run: the summary to read before approving a plan. Writes nothing.',
+          LlmPlan.section('Summary')].join("\n\n")
+    example 'plan:check ./tmp/plan-note-anchor.json'
+    example 'plan:check --md ./tmp/plan-note-anchor.json'
+
+    opt :md, type: :boolean, desc: 'emit the summary as markdown, to paste into a reply'
+
+    proc do |opts|
+      outcome = LlmPlan::Runner.new(load_bundle(opts)).apply(check_only: true)
+      opts[:md] ? puts(LlmPlan::MarkdownReport.new(outcome).to_s) : render(outcome)
+      exit outcome.exit_code
+    end
+  end
+
+  task :verify do
+    desc <<~D
+      Run only the bundle's verify commands.
+
+      For after you have closed a drift by hand, or fixed what a failing verify
+      caught. Exit 0 green, 20 failed.
+    D
+    example 'plan:verify ./tmp/plan-note-anchor.json'
+
+    proc do |opts|
+      exit run_verify(LlmPlan::Runner.new(load_bundle(opts))).ok ? 0 : 20
+    end
+  end
+
+  task :revert do
+    desc 'Undo an applied bundle from <slug>.bak: restore changed and deleted files, remove created ones.'
+    example 'plan:revert ./tmp/plan-note-anchor.json'
+
+    proc do |opts|
+      LlmPlan::Runner.new(load_bundle(opts)).revert.each { |path| say "  restored #{path}", :green }
+    rescue LlmPlan::Error => e
+      error e.message
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lux-hammer
 version: !ruby/object:Gem::Version
-  version: 0.3.21
+  version: 0.3.22
 platform: ruby
 authors:
 - Dino Reic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-08 00:00:00.000000000 Z
+date: 2026-08-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -55,6 +55,7 @@ files:
 - "./lib/lux-hammer.rb"
 - "./recipes/deploy.rb"
 - "./recipes/git-helper.rb"
+- "./recipes/lib/llm/plan.rb"
 - "./recipes/lib/llm/usage.rb"
 - "./recipes/lib/llm/wrap.rb"
 - "./recipes/llm.rb"